t
V
COX iNI! — OF" O Ft T HI
■
S ir~S Cfi
S W iAj }R IP HI Mi O RS EI IE! X T EI iM! S ZC O M S
Brock A* Miller
David E ♦ Mclntyr'
Eugene A* Klotz
(
>
T t Ai E: L BZ O F~
C O M T E M T S
Acknowledgements
I +
I A What this is
1.2 How to use this material
1*3 Further References
1*1 Differences with Starting FORTH
ItS Disk Directory
n»l The FORTH kerneli Differences with fig-FORTH
3I#2 Glossary of the Coin-Op FORTH Kernel
II»3 Atari Extensions
n.4 The fig Editor
1I»5 The Assembler
IV* SWARTHMORE EXTENSIONS
Disk It Miscellaneous words used in some following sections*.
% ("hex follows"), PICK and ROLL, ATASCIBTNTERNAL, INTERNAD-AT ASCII , 2DUP,
2DR0P, HOVE*
COLCRS, ROWCRS, SAVMSC, TXTMSC, TXTROW, TXTCOL, SETVBV, WBLKD, WBLKI
IV. 2 Fast INDEX
IV. 3 CASE
IV *4 Display List Assembler
IV. 5 Cheap Character Generator
IV .6 String Search
IV .7 Print Cowards for Graphics hodes
IV. 8 Screen Copy Routines for Multiple Screen Moves
IV.9 Vertical Scrolling
Disk 2! IV. 10 Player Missile Words (Unshadowed)
IV.ll Player Missile Words (Shadowed)
IV .12 Text Words for Disk Storage of Text
IV .13 Text Compression Text Words
IV. 14 VBLANK Routines
IV. 15 Big WTOBJ
IV .16 Interrupt Driven Sound
QE Disk: IV. 17 The QE Editor
HOW TO WRITE GOOD FORTH
II
THE COIN-OP BOOT
COIN— OP SOURCE
CODE
in.l FORMAT and WTOBJ (Write Bootable Object)
HI. 2 Disk Copy Routines
III .3 Line Printer Words
HI. 4 Formatted Printer Words
Hardware constants J
Ai C K M O W I— EI O G IE! M E M "T S
The programming tools presented here are a byproduct of a grant from the National Science
Foundation - National Institute of Education Program on Mathematics Education and Information
Technology, which resulted in the Swarthmore Trigonometry Project,
Steve Calfee of Atari, Inc. very kindly made available to us his fine version of the fig-FQRTH
programing language, which constitutes the core of this package, Hike Alhaugh of Atari, Inc, was
most helpful in answering our many questions, since only very rudimentary documentation existed,
In creating the Coin-Op FORTH Glossary, we borrowed liberally from the fig-FORTH Glossary by
William F, Ragsdale, provided through the courtesy of the FORTH Interest Group, P.O. Box 1105, Sari
Carlos, CA 9 WO, We also borrowed from All About FORTH by Dr. Glen B, Haydon, Mountain View Press,
Mountain View, CA 19040.
The Assembler Glossary is based on that of William F. Ragsdale, which appeared in the September,
1981 issue of Dr. Dohb's Journal, and we gratefully acknowledge his permission to make use of this.
The following persons served bs programmers for the Swarthmore Trigonometry Project at one time
or another, and made a contribution to our work:
Guy Blelloch, Charles Clinton, David Fristrom, Chris Helck, Gene Kloti, Ben Lewis, David
Mclntyre, Brock Miller, Deborah Reichert, Jay Scott, David Szent-Gyorgyi, and Fred
Thomsen.
The writing and assembly of the enclosed material was done by
David Fristrom, Gene Kloti, Ben Lewis, David Mclntyre, Brock Miller, Tom O'Brien, and Fred
Thomser:*
Brock Miller was in charge of the writing and assembly and David Mclntyre was his straw boss.
The typing was ably handled amidst great chaos by Pamela Moench, Nancy Burton, and Bruce
Mallory.
This project raced for its existence with the first issue of the Schmaliried-Ryan union. We
won, and affectionately dedicate this to her or him.
Gene Kloti
Swarthmore College
May 28, 1983
Bad • FORTH benedictions *♦
Don't forget to FLUSH
May the FORTH be with you.
!♦! WHAT THIS IS
This package consists oft
(a) the Coin-Op version of the FORTH programing language residing on the disk harked Atari Coin-Op
FORTH* version l#4Vt
(b) the source code for a number of programs in FORTH, to be found on the disks narked "Swarthmore
l»t "Swarthmore 2", and "Swarthmore QE"*
(c) Discussion and glossaries for all the above*
All disks except QE boot to unadorned Coin-Op FORTH* QE boots to an embellished version
described in the next section*
Coin-Op FORTH was developed by Steve Calfee at Atari, Inc* and the disk enclosed is, except for
3 V ery few minor changes, exactly what he has informally distributed* This is a well-wrought, tight
version of FORTH* Among its notable features are an excellent compile time* The 32 line screens
allow for writing clear code (see Section V* How to Write Good FORTH)*
The Swarthmore disks contain programming tools which were developed over a two-year period by
the Swarthmore Trigonometry Project* These range from simple aids for the beginning programmer to
more sophisticated program development tools* He hope that the doojmentation will be of use to the
corresponding range of programmers* In almost all cases, we provide a discussion of each FORTH word,
along with the source code (except for much of the booted material on the Coin-Op disk)*
Hhat this isn't
This is not a complete FORTH tutorial - we recommend its use in conjunction with a standard
FORTH text, such as Starting Forth *
This is not a complete Atari tutorial - see the references in the next section*
This is not a version of FORTH for all users* In particular, it lacks a floating-point
arithmetic package (because floating-point arithmetic is much slower - see the discission in Chapter
5 of Starting FORTH ) * In most instances, this should not be a disadvantage*
The code is probably not error free - although we have tested arid used everything and know of no
errors* (Until it is used for some time by a wide variety of users, most code is not error free)*
The documentaton will not be perfect for everyone* At least we've worked hard to produce what
we would have liked to receive ourselves*
TO USE THXS MATERIAL
Remove any cartridges from your Atari 100 or 800 , turn on the disk drive, insert the Atari
Coin-Op disk, and turn on the computer. Unless your disk drive's speed is badly out of adjustment or
Magnetic disaster has struck the disk, after a short tine you should get the message H f ig-FORTH
it4v* M You are now in FORTH ♦ Feel free to play* The worst you can do (if your disk is write
protected) is to crash the system, in which case try the Reset button, or for a high quality crash,
reboot*
■ Such discovery learning will not get you very far very fast or very thoroughly, arid we recommend
you work along with a good text* Two sections hence, we chronicle the differences between Coin-Op
FORTH and the FORTH referred to in the excellent text, Starting FORTH * You'll find our Glossary of
the Coin-Op Kernel, Section 11*2, a handy companion.
One of the first things you'll want to do is make a backup copy* If you have more than one disk
drive, see section ITL2 on Disk Copy Routines, and proceed accordngly* Things are tougher if you
only have one drive. See Section IEL1 HTOBJ to get a copy of the booted part of any disk, but
transferring source screens is lengthy. To transfer two individual screens from a source disk to a
destination disk, stick in the source disk and type the incantation*.
1st .screen* number BLOCK DROP UPDATE [RETURN]
2nd* screen* number BLOCK DROP UPDATE [RETURN]
Then insert the destination disk and type FLUSH (and hit [RETURN]) ♦ Unfortunately, this won't work
for more than two screens at a time. To see the screens before transferring them, replace BLOCK by
LIST in the above.
There are two changes in your programming environment you might want to make at first. Type
1 WARNING ! [RETURN]
to receive error messages rather than error numbers. (The error messages are on screens 2 through
5). Coin-Op FORTH comes in hexadecimal. Typing DECIMAL will get you into what is likely to be a
more familiar environment. However, hitting System Reset or rebooting will return you to hex. To
create a disk which will boot to decimal (and stay there with System Reset), type
' DECIMAL CFA ' ABORT 2+ ! [RETURN]
Then do a HTOBJ (see Section HI#1) so that these changes will be made part of the boot.
You might want to consider some further additions to your booted FORTH system. The followng
seem particularly useful 5 Fast INDEX, $ (which causes the next number to be interpreted as
hexadecimal), and the QE editor (which is large, but worth it, we think). All are in Section IV.
After such additions are compiled, it is necessary to do a HTOBJ (Section III.l) to make them part of
the boot*
The Swarthmore QE disk boots with all these treats but without 1 WARNING !♦ However, the
object code extends through screen 8, so you'll get crazy error messages with 1 WARNING ! unless you
insert a disk which has them on screens 2-6.
In using the documentation, we expect you to have certain references available. For the Atari,
we assume you have a 400/800 Basic Refernce Manual, which comes with the computer. For deeper
hardware questions, we sometimes refer to De Re Atari , by Chris Crawford, et al, Atari, Inc.,
1981,APX-90008. For matters pertaining to FORTH, we refer you to Starting FORTH, by Leo Brodie,
Prentice-Hall, 1981.
Sometime, please read Section How to Write Good FORTH*
For the ft tar it
Above arid beyond De Re Atari, you flight wish to consult the Atari 400/800 Hardware Manual or the
Atari 400/800 Operating Systen User's Manual, available fron Atari, Inc*
For FORTH:
The following have proved useful*
Glenn B« Haydon, All About FORTH, Mountain View Press, 1982*
(Good glossary of words frOM several different FORTHs*)
Mitch Derick t Linda Baker, FORTH Encyclopedia, Mountain View Press, 1982 «
(More detailed than the above*)
C#Hi Ting, Systems Guide to Fio FORTH , Offete Enterprises, Inc*, 1980*
(Good for how FORTH works* )
Hillian F« Ragsdale, fig-FQRTH Irrstallation Manual , Forth Interest Group, 1980*
All the above are available frort Mountain View Press, P*Q* Box 4656, Mountain View, Ca*, 94040, (415)
961-4103*
Serious FORTH users should consider joining the FORTH Interest Group* Their journal, FORTH
Dimensions , nakes interesting reading* FORTH Interest Group, P*0* Box 1105, San Carlos, Ca* 94070*
(415) 962-8653*
1*^ C C3I2NI — C3P 3 FORTH VS* STARTING
FORTHs based on the fig (FORTH Interest Group) Model, such as the CoirrOp FORTH kernel, are
different in some significant ways from the version of FORTH described in Starting FORTH (which is
nonetheless an excellent introductory text for the beginning Coin-Op FORTH user)* Following is a
list, referenced by Starting FORTH page number, of words in Starting FORTH which either have
different names or are not used at all in Coin-Op FORTH ♦ There are also a few notes included on more
general differences between the two* This list of differences is fairly complete, but it should not
be regarded as comprehensive* In particular, there are a nunber of words included in Coin-Op FORTH' s
kernel which are not in Starting FORTH * and which are not Mentioned in the following list* These
range from words used to manipulate headers (NFA, PFA, etc*) to disk buffer words (ELOCK, BUFFER) to
words for listing the dictionary (MUST) ♦ After you are familiar with Starting FORTH , browse through
the Coirr-Op FORTH glossary to become familiar with these words*
ESi 19 - Coin-Op FORTH allows up to 31 characters of a name to be stored in the dictionary*
PP« 57-58 - The fig-FORTH editor is very different from that described in Starting FORTH ? the
Starting FORTH discussion of FORTH' s screen-based system will nonetheless be quite useful to the
CoirrOp FORTH user* The following words are basically the same in Starting FORTH and Coin-Op FORTH**
LIST, LOAD, (, FLUSH, COPY, FORGET*
ESi 91 - The fig-FORTH word 0= takes the place of HOT in Coirr-Op FORTH*
ESi 101 - The fig-FORTH word -DIP takes the place of ?DUP in Coin-Op FORTH*
ESi 101 - AE£)RT H does not exist in Coin-Op FORTH*
ESi 107 - The words 1- and 2* do not exist in fig-FORTH, but they are included as part of the Coin-Op
FORTH boot* The words 2- and 2/ are included in neither fig-FORTH nor CoirrOp- FORTH*
ESi M§ - In Coin-Op FORTH, NEGATE is called HINUS*
ESi Hi - The word F does not exist in CoirrOp FORTH*
ESi 132 - U*R does not exist in Coin-Op FORTH*
ESi 139 - In addition to BEGIN *♦♦ UNTIL and BEGIN ♦** WHILE *** REPEAT, Coin-Op FORTH also supports
BEGIN ♦♦♦ AGAIN, where AGAIN executes an unconditional branch back to BEGIN*
ESi 132 - PAGE does not exist in CoirrOp FORTH* Clear ing the screen is performed by the Coin-Op
FORTH word CLEAR*
ESi 161 - The words U/MOD, U*, and /LOOP do not exist in Coin-Op FORTH* Coin-Op FORTH does include
the word U/ (unsigned divided by), which is not included in Starting FORTH *
ESi- 162 - The word OCTAL does not exist in Coin-Op FORTH. Octal can be set by the command 8 BASE ! *
ESl • The only punctuation mark which may be used during input to indicate a double nunber is ♦
(period) ♦
T*4 Coin-Op FORTH vs« Starting FORTH, p »Z
■
£0^. 173 - The double nuriber operators D-, DHAX, DMIN, D= t D0=, DC, and IXK do not exist in Coin-Op
FORTH* The word DNEGATE has been replaced by the f ig-FORTH word DMINUS* Coin-Op FORTH includes the
word Di which is not Mentioned in Starting FORTH .
E£i 174 - M+ and W do not exist in Coin-Op FORTH* Coin-Op FORTH does include two nixed length
operators, M/HOD and D8U*, which are not included in Starting FORTH *
££*_ 183 - VARIABLE takes an argument on the stack in Coin-Op FORTH, arid stores this argument in the
newly defined variable's parameter field*
PQ, 193 * Double length variables and constants do not exist in Coin-Op FORTH** thus, 2VARIABLE,
2C0NSTANT, 2!, and 26 are not defined*
£2^ 205 - DUMP does not exist in Coin-Op FORTH*
£2^ 217 - EXECUTE requires the CFA, not the PF A, of a word* Using the PFA will crash the system*
E2*. 218 - t'1 is not defined in Coin-Op FORTH, since ' is defined as being immediate* Thus ' can be
used in place of C' 3 in a colon definition*
pp» 220-221 - The structure of Coin-Op FORTH headers is significantly different from that described
in Starting FORTH * See the discussion of Coin-Op FORTH headers, linking and vocabularies* EXECUTE
expects the CFA, not the PFA, of a word*
do. 225 - The word EXIT is called }S in Coin-Op FORTH*
£cu 233 - H is called DP in Coin-Op FORTH*
ES*. 235 - 'S is called SPG in Coin-Op FORTH*
236 - SO is not directly available to the user in Coin-Op FORTH* See the glossary entry for SO*
pp. 232-233 - The Starting FORTH discussion of vocabularies applies quite well to Coin-Op FORTH, as
far as it extends (the one exception is that 5 sets CONTEXT to CURRENT, not to FORTH)* The Coin-Op
FORTH linking system is significantly different from other FORTHs, however, and this effects
vocabularies. See discussion of linking arid vocabularies in Section XI tit
22± 256 - FLUSH does not "forget" that a buffer is in memory in Coin-Op FORTH 1 , it only turns off the
"updated" flag*
£3*. 261 - >TYPE does not exist in Coin-Op FORTH*
ES± 266 - MOVE and <CHDVE are not defined in Coin-Op FORTH*
££♦_ 270 - WORD does not leave the address of HERE on the stack* TEXT does not take a delimiter on
the stack? instead, it reads all characters up to the next carriage return*
£□*, 272 - >IN is called IN in Coin-Op FORTH*
£2_*_ 277 - BINARY ( CONVERT ) does not exist in Coin-Op FORTH*
£^ 281 - -TEXT is not defined in Coin-Op FORTH*
£2^ 291 - The word CREATE is called <BUILDS in Coin-Op FORTH* The Coin-Op FORTH word CREATE only
xrr—
FORTH vs * Star t, i n<2 FORTH t p ♦ 3
creates 3 header for new dictionary entries ♦
E2± 301 - Coin-Op FORTH uses (DO), not 2>R*
ESt 303 - (LITERAL) is called LIT in Coin-Op FORTH.
Coin— Qp FORTH Disk :
Screens 2-5 Error Messages
9 Screen originally used to compile assembler
11 Disk copy routines CUL2)
13-19 The Assembler (11*5)
20 Undocumented
21-25 The fig Editor (11*4)
26 OS and Hardware constants (in Glossary , 11*2)
27-29 Undocumented
30 DECUS FORTH additions (in Glossary , II* 2)
31 Display list disassembler, undocumented
32-33 FORMAT and HTOBJ (m*l)
35-36 Uridocumented
37-38 Line Printer words (HM)
39-^3 Formatted printer words (111*1)
11-16 Undocumented
Swarthnore Disk. ±t
Screen 1 Directory
2-5 Error messages
7-17 IV* 1 Miscellaneous
20 IV ,2 Fast INDEX
22-23 IV. 3 CASE
IM Display List assembler
29 IV* 5 Cheap character generator
31-31 IV* 6 String search
37-18 IV*7 Print commands for graphics modes
50-51 IV* 8 Screen copy routines
53-55 IV*9 Vertical scrolling
Swarthfiore D i sk 2*
Screen 1 Directory
2-5 Error messages
10-13 IV* 10 Unshadowed Player Missile words
15-20 IV* 11 Shadowed Player Missile words
22-31 IV* 12 Text words for disk storage of text
33-19 IV* 13 Text compression text words
52-53 IV* 11 VBLAHK routines
55-61 IV* 15 Big HTOBJ
Su>3T"t,HfiPT"e QE Disk X
Screens 0-8 Boot source code continuation
11-77 Source code for QE (IV* 17)
NOTE : The QE disk boot contains QE (and therefore the Miscellaneous words* CASE, Display List
assembler, arid unshadowed Player Missiles)*, it also has Fast Index* It boots to decimal*
All other disks boot to Coin-Op FORTH*
INTRODUCTION
The documentation of the Coin-Op FORTH hoot is divided into four parts, which correspond to the
four sections of the hoot itself* These four sections incli.de:
1) 3 modified f ig-FORTH kernel
2) Atari graphics, sound t arid device control words arid a few other miscellaneous words
3) a fig-FORTH editor
4) a fig-FORTH assembler*
The section on the Coin-Op FORTH kernel consists of a list of the modifications which have been
made to the fig-FORTH model and brief discussions of the most important departure from that model
(the vocabulary/linking system) and of the Atari-specific disk access words) these are followed by a
complete glossary of the kernel* The discussion of each extension includes a brief discussion of how
to use the important words in that exter»ion f followed by a complete glossary of the extension*
11*1 THE FORTH KERNEL
COIN-OP FORTH VS* FIG-FORTH
■ ■ ■ ■ ■ ■ ' • ■
The Coin-Op FORTH kernel (i*e*, the 250 or so words which constitute the heart of FORTH) is
based on fig-FORTH* However, a number of modifications have been made* These 3re listed below* for
the convenience of those who are already familiar with fig-FORTH* (The sections on disk access and
disk buffers* headers, links, arid vocabularies will also be of use to those who are not familiar with
fig-FORTH*)
The following fig-FORTH words are not included in Coin-Op FORTH* +BUF , BLOCK-READ , BLDCK-HRTTE
, DUST (this word was used to list the vocabulary? it had nothing to do with graphics display
lists), DUMP , HON , MOVE , USE ♦
The following words are included in the CoirrOp FORTH kernel but are not part of the fig-FORTH
model (for explanations of their usage, see the Coin-Op Kernel Glossary*, in addition, some of these
words will be discussed in more detail in the sections on disk access arid disk, buffers, headers,
links, and vocabularies)** *LM(S , 7BITS , ALT , EfXD , D8U* , DDIO , DECMAP , DIO , FLUSH , HASH ,
HIMEM , ICAL , ICCM , ICLL , J , PHYSOFF , PTAB , SECIO , SIO , TCIOV , IK *
Headers, Links, and Vocabularies
Coin-Op FORTH executes dictionary searches much, much faster than standard fig-FORTH 4 , this in
turn means that much less time is spent by the programmer in compiling FORTH words and screens* The
vastly increased speed was obtained by modifications to the header structure of dictionary entries
and by the introduction of "sub-vocabularies" ♦ Most users will not need to understand these
differences in order to use FORTH to full advantage* Other users will require such an understanding,
however, and still others will simply be interested in what makes FORTH tick* The following
discussion should be helpful*
XX* 1 The FORTH Kernel, P* 2
Headers
Noma! fig-FORTH headers have the following structure*
HFA
a name field, starting at NFA, which has a variable number of bytes (up to 31) ♦
LFA
following the name field, a two byte link field, which contains the HFA of the first word
in the sane vocabulary which immediately precedes this one*
CFA
following the link field, a two byte code field which points to the word's execution code*
PFA
following the code field, a variable length parameter field*
In Coin-Op FORTH, the link, field cones before the name field, with the code field coning
immediately after the name field* The structure is thus*
LFA NFA CFA PFA
This improves the speed of dictionary searches, since the LFA of a word will have a fixed offset of
-2 from the NFA rather than a variable offset*
NOTE** in fig-FORTH, the last character in a nane field has its high bit set ($80)* Because only
this character can have this bit set, nates cannot have ATASCII inverse characters in then. To wake
sure that this is the case, all words in the input stream are operated on by the word 7BITS, which
changes any inverse characters in a word to normal characters by setting the high bit to 0* Thus, to
FORTH inverse arid normal ATASCII characters in a nane are identical*
Linking and "Sub-vocabularies"
Normal fig-FORTH has all words in a given vocabulary linked together } ths most recently defined
word links directly (through its LFA) to the NFA of the word defined before that, which links to the
word before that, and so on, down to the very first word in the vocabulary* (See Starting FORTH,
PP ♦212-44, for a good discussion of vocabularies arid linking*) Coin-Op FORTH has Modified this
system through the creation of "sub-vocabularies" within vocabularies*
During compilation, each word in a vocabulary is placed in one of 8 sub-vocabularies* The
number of sub-vocabularies is determined by the constant *LBKS, which is set to 8*) These
sub-vocabularies nay be numbered fron 0 to 7. Hhich sub-vocabulary a word belongs in is deternined
by the ATASCII value of the first character of that word's nane* That value is divided by 8, and the
renainder (0-7) determines which sub-vocabulary the word will belong to* Thus, a word beginning with
H (ATASCII value $48) will be placed in sub-vocabulary 0, as will a word beginning with X ($58), 8
($38), or E ($40)* A word beginning with L ($4C), on the other hand, will be placed in
sub-vocabulary 4* while a word beginning with N ($57) will be in sub-vocabulary 7, and so forth*
Thus, the words in each vocabulary have been "hashed", according to their ATASCII value, into 8
groups*
The words in each sub-vocabulary are linked together in the nornal manner} the LFA of the most
recently defined word in a sub-vocabulary points to the NFA of the word in the same sub-vocabulary
defined just before that, arid so forth down to the first word defined in that sub-vocabulary ♦ Hords
in one sub-vocabulary thus are linked only to each other, arid not to those in arry other
sub-vocabulary*
Now, look at what happens when a dictionary search occurs* As an example, assume that the word
DUP has just been encountered in the input stream* The search routine takes the first letter (D) of
II ♦! Thie FORTH Kernel, p* 3
this word, and fro* it determines which sub-vocabulary the word nust be in, if its exists at all*
(This task of "hashing" is performed, logically enough, by the word HASH*) In the case of DUP,
sub-vocahulary *4 is duly searched, arid DDF' is found ♦ The point is that the other 7 sub-vocabularies
need not be searched , and thus on average onl^ 1/8 as Many words will need to be looked at in any
given dictionary search in Coin-Op FORTH, as opposed to in a FORTH which uses only one "link-chain"*
This is the Main reason why Coin-Op FORTH compiles code so nuch faster than fig-FORTH*
Vocabularies
A knowledge of the structure and purpose of FORTH vocabulary definitions is necessary in order
to under stand the following discussion* All About FORTH by Glen B* Haydon and FORTH Encyclopedia by
Derick and Baker contain good discussions of vocabularies* It should be noted that new vocabularies
need not chain directly to the FORTH vocabulary*, any vocabulary way serve as a "parent vocabulary".
This in turn allows an ever-expanding branching structure of vocabularies within the dictionary*
Eventually, of course, all vocabularies will chain at least indirectly to FORTH*
The changes to the header structure and the addition of sub-vocahularies have necessitated two
changes to the structure of vocabulary definitions in Coin-Op FORTH*
h Instead of one vocabulary entry pointer (or, if you prefer, "Vocabulary link field")
in each vocabulary definition, there are now eight, one for each sub-vocahulary* Since
each entry pointer needs 4 bytes (two for the pseudo-nane field, two for the link), a
total of 32 bytes is required* Sub-vocabulary *0 uses bytes 1 to 4 as its entry pointer,
sub-vocahulary *2 uses bytes 5 to 8, and so forth* In this way, sub-vocabulary *n of a
child vocabulary chains to sub-vocabulary #n of its parent*
2^ The pseudo-NFA of each entry pointer now follows the LFA, rather than vice versa*,
this is due to the change in header structure decribed in the above section on Headers*
MUST
MUST has been modified so that it will still print out the CONTEXT vocabulary words in the
order in which they are placed in the dictionary* However, in vocabularies to which the CONTEXT
vocabulary chains (unless the CONTEXT vocabulary is FORTH, of course) all of the words in
sub-vocabulary *7 will be listed in order first, followed by those in sub-vocabulary 6, 5, and so on.
(This is because MLIST sets up a table of the NFAs of the next word in each sub-vocabulary} the word
in this table with the highest NFA is printed by MUST, arid its NFA is replaced with that of the word
to which it links} this process then repeats for the next word, arid so on to the bottom of the
dictionary* This works fine, until all of the NFAs in the table are the "pseudo NFAs" in the parent
vocabulary? at this point, sub-vocabulary *7's NFA is the highest address in the table, as are the
NFAs of all of the subsequent words in the parent vocabulary's sub-vocabulary *7* Thus, all words in
sub-vocabulary M will be listed until it is exhausted, after which all words in sub-vocabulary *6
will be listed, etc*) This will continue until the word FORTH is itself encountered, after which
words will again be listed in order of their physical location in the dictionary as a whole*
Disk Access and Disk Buffers
Many users will never need to worry about Coin-Op FORTH' s primitive disk access and disk, buffer
words*, the higher level words LIST, LOAD, BLOCK, arid BUFFER provide a great deal of flexibility and
Coin-Op FORTH does use the standard fig-FORTH word R/W* Below the level of these words, however,
XI ♦! The FORTH Kernel, P* 1
Coin-Op FORTH 's disk words are tailored to the Atari arid as such they differ fro* nornal fig-FORTH
usage * The following discussion is intended for those who either need to know or are interested in
knowing what these differences are* The one section which nay he of wore general interest is that on
the numbering of disk blocks*
Disk Access
Coin-Op FORTH dos not use the standard fig-FORTH disk access words , BLOCK-READ and EL0CK4&TTE*
Instead, CoirrOp FORTH utilizes words which directly call the Atari SIO routines* These words are
SECIO and SID, which in turn are called by DIO (for single density disk drives) arid DDIO (for double
density disk drives), basically, the procedure for disk, access is to set up a device control block
(see the Atari OS Manual and the words ICAL, ICCM, ICLL) and execute SECIO*
Screen Numbering
1* Coin-Op FORTH allows for a difference between physical and logical screen numbering* This is
accomplished by storing a value into the user variable FWSOFF (normally set to 12)* This value is
added by the disk access words to whatever logical block., number is supplied by the user in order to
obtain the physical block number* This allows the user to put the bootable object on a disk onto
"negative" logical screens* Note that it is very difficult to use logical screen 0 on a disk to hold
source code (see INTERPRET)*
2* The logical screen supplied by the user is interpreted by Coin-Op FORTH as follows*
Each block. * is 16 bits, of which the highest bit is not used* The low 11 bits ($0 -
$7FF) indicate the screen number* The next two bits (12 arid 13) indicate the drive *, and
the two bits above those (14 and 15) indicate the drive type* Consult the following chart
to see what values to add to a given logical block number*
Add this value 4 * To access drive ♦*
$0000 1
$0800 2
$1000 3
$1800 1
Add this value: To access drive type!
$0000 810-type 5 1/1" single density
$2000 815 or 8" double density
$4000 8" single density DEC interleave
$6000 8" single density non-interleaved
Disk Buffer Control
Coin-Op FORTH uses a table called FT AD to control disk buffers* This table contains four
"entries", each corresponding to a disk, block* The first entry contains information on the most
recently accessed block, the second contains information on the next most recent block, and so forth*
At the moment, only two disk buffers are used by Coin-Op FORTH, and as such only the first two
entries of PTAB are used* The two buffers each consist of $400 (IK) bytes, and they begin at $500
and $900, respectively*
Each entry in the disk buffer table consists of 5 bytes* The first two bytes contain the
XI ♦! THe FORTH Kernel * p* 5
logical block, number* The second two bytes contain the starting address of the buffer in which the
block is contained* The last byte indicates the status of the buffer (0 = not in use, 1 = in use, 81
= updated)*
When a new block, is accessed it is placed in the buffer which was least recently used* The
block number, buffer address, and status of this block are placed in the first entry in the disk,
buffer table, while the old contents of the first entry are placed in the second entry* (If a third
buffer was in use, the contents of the third entry would indicate the least recently accessed block,
and the contents of the second entry would be placed in the third entry when a new block, was
accessed} likewise with a fourth buffer*) If the block in the least recently accessed buffer is
Marked as updated, its contents are written to disk, before a new block is read into that buffer*
The contents of the variable PREV point to the first byte of the ttost recently accessed buffer
entry (entry *1) in PTAB* The contents of the variable ALT (which roughly corresponds to the
fig-FORTH word USE) point to the entry for the least recently accessed buffer (entry *2)* FORTH and
the user can thus access the disk buffer information via these words* (MOTE I a third disk buffer
could be added by pointing ALT to the third entry in PTAB (PTAB +$A) and placing a buffer address
into the third and fourth bytes of this entry* The sane technique could be used for a fourth disk
buffer* DO HOT put the new buffer or buffers right above the old ones! FORTH starts at $D00* Put
thett sonewhere above the dictionary*
2 Coin-Op FORTH Kernel t GIqssbf^ ^ p*1
n addr —
Store 16 bit value r« at address* Pronounced "store" *
Save the stack position in CSP* Used as part of
dl — dZ
Generate, fro* a double nutter dl, the next ATASCII character which is placed in an output
string* Result d2 is the quotient after division by BASE and is Maintained for further
processing* Used between <* and #>♦ See *S*
d — addr count
Terminates numeric output conversion by dropping d, leaving the text address arid character
count suitable for TYPE*
— n
Constant leaving the number of link chains in each vocabulary* For a full explanation of
the linking systeh (which is different from that of normal fig-FORTH), see the discussion
of linking which precedes this glossary*
dl — d2
Convert all digits of double-number dl to their AT ASCII equivalents, adding each to the
pictured numeric output text, until- the remainder is 0 (this remainder is left as d2)* A
single 0 is added to the output string if the initial value of dl is 0* Used between <#
and *>.
— addr
Used in the form**
' rvm
If executing, leaves the PFA of the next word accepted fro« the input stream* If
compiling, compiles the PFA as a literal*, later execution will place this value on the
stack.* If the word is not found after a search of CONTEXT and CURRENT, an appropriate
error message is given* This is defined as an immediate word. Pronounced "tick"*
Used in the form**
( cccc)
Accept arid ignore comment characters from the input stream, until the next right
parenthesis* Since it is a FORTH word, ( Must be followed by at least one blank* It nay
be used freely while executing or compiling* Contents nay not be longer than 255
characters, arid an error condition exists if the input stream is exhausted before the
right parenthesis*
The run-time procedure compiled by +L00P, which increments the loop index by n and tests
for loop completion* See +LOOP*
XX ♦ 2 Coin— Op FORTH Kernel, Glossary, p. 2
(.")
The run-tirte procedure, compiled by #" which transnits the following tit-lite text to the
selected output device* See
(JCODE)
(ABORT)
(DO)
The run-time procedure, compiled by *,C0DE, that rewrites the code field of the most
recently defined word to point to the Machine code sequence which follows JCODE* See
JCODE*
Executes after an error when HARMING is -1J also executes after a RESET or BREAK* This
word normally executes ABORT , but May be altered (with care) to execute a user's
alternative procedure*
The run-tine procedure compiled by DO which Moves the loop control paraMeters to the
return stack* See DO*
(FIND) addrl addr2 — pfa b tf (found)
addri addr2 — ff (not found)
Searches the dictionary starting at the NFA addr2, hatching to the text at addrl* Returns
paraweter field address, length byte of the narte field and boolean true if a Match is
found* If no Match is found, only a boolean false is left*
(LINE)
ni n2 — addr 32
Converts the line nuhher nl arid the screen n2 to the starting address of that line in the
disk buffer* If screen n2 is not already in memory, it is read from disk to buffer* The
count of 32 indicates the length of a text line.
(LOOP)
The runrtiwe procedure coMpiled by LOOP,
completion. See LOOP*
Increments the loop index and tests for loop
(NUMBER)
dl addrl — d2 addr2
Convert the AT ASCII text beginning at addr 1+1 with regard to BASE* The new value is
accumulated into double number dl, being left as dZ. Addr 2 is the address of the first
unconvertable digit* Used by NUMBER*
nl n2 — n3
Leave the arithmetic sum n3 of nl+n2.
+ !
n addr —
Add n to the 16-bit value at the address* Pronounced H
ii
Hv2 Coin-Op FORTH Kernel, Glossar^ t p*3
nl n2 — n3
Negate nl if n2 is negative*
nl — (run-tine)
addr n2 — (conpil-tine)
Used in 3 colon-definition in the fornt
DO .♦* nl +LD0P
At run-tine, +L00P selectively controls branching back to the corresponding DO based on
nl t the loop index and the loop Haiti The signed increment nl is added to the index and
the total is compared to the Unit* The branch back to DO occurs until the new index is
equal to or greater than the Unit (nl>0), or until the new index is equal to or less than
the linit (nl<0)* Upon exiting the loop, the parameters are discarded and execution
continues beyond LOOP*
At ccwpile tine, +LD0P compiles the run-tine word (+L00P) arid the branch offset computed
trow VEPE to the address left on the stack by DO* n2 is used for compile tine error
checking*
n — addr
Leave the nenory address which is n bytes above the "origin" ♦ n is given in terns of
bytes* This definition is used to access or nodify the boot-up parameters at the origin
area* The "origin" in Coin-Op FORTH is at *D00*
Allots 2 bytes in the dictionary and stores n there* Pronounced! "coma"*
nl n2 — n3
Subtract nZ fron nl arid leave the difference as n3* '
Used on a disk screen* Causes the next disk screen to be loaded* Interpretation
continues on this screen* (Pronounced "next-screen")*
n — n (zero)
n — n n (non-zero)
Reproduce n only if it is non-zero* This is usually used to copy a value just before IF*
to eliminate the need for an ELSE part to drop it*
— pfa b tf (found)
— ff (not found) .
Accepts the next text word (delimited by blanks) in the input strean to HERE* and searches
the CONTEXT and then CURRENT vocabularies for Matching entry* (Searches continue on into
parent vocabularies} the CURRENT vocabulary is searched only if it is not the sane as the
CONTEXT vocabulary)* If found, the dictionary entry's paraneter field address* its length
byte, and a boolean true is left* Otherwise, only a boolean false is left*
II *Z Coin-Op FORTH Kernel, Glosssr^, p*^
-TRAILING 3ddr nl — addr rtZ
Adjusts the character count nl of a text string beginning at addr to suppress the output
of trailing blanks* i*e* the characters at addr+nl to addr+nZ are blanks* Read "not
trailing"*
i nl nZ — n3
Leaves the signed arithmetic product of two signed numbers*
1/ nl nZ n3 — vA
Leaves the ratio rrt = nl*nZ/n3 where all are signed numbers* Retention of an intermediate
31 bit product permits greater accuracy than would be available with the sequence**
nl nZ x n3 /
ti
4
nl nZ n3 — ifi n5
Leaves the quotient n5 arid remainder rrt of the operation nl*nZ/n3* A 31 bit intermediate
product is used (as for
Display n f converted to AT ASCII according to BASE t in a fixed-field format* Prints the
sign only if n is negative* A trailing blank follows* Pronounced ,, dot ,, «
Used in the form**
*" cccc"
Accepts the following text from the input stream, delimited by " (double-quote)* If
executing, the text is transmitted to the output device* If compiling, compiles the text
(with the count in the first byte) along with the execution procedure (♦") so that later
execution will transmit the text to the output device* The text may be up to 255
characters long*
♦LINE nl n2 —
Print line nl of disk screen n2 on the terminal device* Trailing blanks are suppressed*
All AT ASCII control characters are printed*
*R nl nZ —
Prints the number nl right aligned in a field of width n2* No following blank is printed*
If nZ < If no leading blanks are supplied*
/ nl n2 — n3
Divides nl by nZ and leaves the signed quotient n3 (which is rounded toward 0)*
nl ri2 — n3 rrf
Divides nl by n2 arid leaves the remainder n3 arid quotient tA* The remainder n3 has the
same sign as the dividend nZ*
IX ♦ 2 Co i n— Op FORTH Ker ne 1 1 Glossary t p ♦ 5
These snail numbers are used so often that it is attractive to define then by name in the
dictionary as constants, because constants take less dictionary space arid less dictionary
search tine than do numbers ♦
n — f
Leaves a true flag if n is less than zero (negative), otherwise leaves a false flag*
n — f
Leaves a true flag if n is equal to zero, otherwise leaves a false flag*
The run-time procedure to conditionally branch* If f is false (zero), the in-line
parameter which follows it is 36^6 to the interpretive pointer to branch ahead or back.*
Compiled by IF, UNTIL, arid WHILE*
n — ri+1
Increments n by 1*
n — n+2
Increment n by 2*
addr n —
Sets the high bit of each byte of the n bytes starting with addr to 0* This converts any
characters which are in inverse representation to their normal representations} FORTH
treats inverse characters which occur in word names as if they were normal characters*
Used in the form**
t cccc ♦♦♦ *,
Creates a dictionary header for cccc in the CURRENT vocabulary, sets CONTEXT equal to
CURRENT, arid sets compile mode* Also, sets the CFA of cccc to point to run-tine code
which follows i in the dictionary* The compilaton addresses, CFA, of subsequent words in
the input stream which are not immediate will be compiled into the dictonary by INTERPRET t
to be executed when cccc is later executed* (Immediate words, i*e* those with their
precedence bit set, will be executed when they are encountered.) Compilation of CFAs will
continue until I is encountered.
If a word which is part of a colon definition is not found after a search of both
the CONTEXT and CURRENT vocabularies, an error conditon exists.
Terminates a colon-definition and stops further compilaton. Compiles the run-time routine
*,S. If compiling from mass storage arid the input stream is exhausted before } is
encountered, the machine may crash.
II. 2
Kernel, Glossary , p . <£>
♦ I
Used in the form J
S ccc . ♦♦♦ JCCDE assembly mnemonics
Stops compilation arid terminates a new defining word cccc by compiling (*,C(X>E)* Sets the
CONTEXT vocabulary to ASSEMBLER , assembling to machine code the mnemonics which follow it*
When cccc later exeDjtes in the formi
cccc nrmn
the word nnrm will be created, and its execution address will contain the address of the
machine code following JCODE in cccc* That is, when nrmn is executed, it does so by
jumping to the code after mm*-
Stops interpretation of a screen. }S is also the rurrtime word compiled at the end of
colon-definition which returns execution to the calling procedure*
nl ri2 f
Leaves a true flag if nl is less than n2{ otherwise leaves a false flag*
•(BUILDS
Initializes pictured numeric output, which uses the words*"
<* * *S SIGN !>
The conversion to ATASC3I is done on a double number and produces text at PAD*
<BWLDS is used in conjunction with DOES) to created defining words* Used in the form!
J cccc <BUILDS ♦♦♦
D0ES> ***
Hhen cccc is later executed in the form cccc bbbb, <BUILDS creates a dictionary entry for
the new word bbbb* First, a header for bbbb is created* Then the sequence of words
between <BU3LDS and D0ES> establishes a parameter field for bbbb* Hhen bbbb is later
executed, its PFA will be placed on the stack and the sequence of words following D0ES> in
cccc will be executed*
nl n2 — f
Leaves 3 true flag if nl=ri2 i otherwise leaves a false flag.
Leaves a true flag if nl is greater than n2J otherwise leaves a false flag.
>R
n
Removes the top value from the stack and places it on the return stack*
balanced with R> in the same nesting level of a colon definition*
Use of >R must be
?C0MP
addr —
Prints the contents of memory location addr in free-format according to the current base*
error message if rot compiling*
XI* 2 Coin-Op FORTH Kernel* Glossary, p*Z
?CSP
error Message if stack position differs fro* value saved in CSP.
Ill ■ ■ ■ Mto^
TERROR
f n —
Issues an error Message nunber ft, if the boolean flag is true.
7EXEC
Issues an error Message if not executing*
7LDADING
?PAHB
7STACK
Issues an error Message if not loading*
Issues an error Message if nl does not equal n2* The Message indicates that cottpiled
conditionals do not Match*
Issues an error Message if the stack is out of bounds %
7TERMINAL
PerforMS a test of the terMinal Keyboard to see if the break key has been pressed. A true
flag indicates the key has been pressed* (In Coin-Op FORTH* this routine always returns a
false flag? testing for BREAK occurs during TYPE and KEY*)
addr — n
Leaves the 16 bit contents of addr on the stack* Pronounced "fetch"
Clears the data and return stacks and enters execution Mode* Returns control to the
operators terMinal* printing a Message appropriate to the installation* Execution of the
abort routine is vectored through ABORT to (ABORT) J the actions of ABORT can thus be
changed as the user desires (as long as (ABORT) is involved as the final part of the
changed routine)*
AES
nl — n2
Leaves the absolute value of a nunber*
AGAIN
— (execution)
addr n — (coMpiling)
Used in a colon-definitiion in the for-M*
BEGIN ♦♦♦ AGAIN
At rurrtiwe, AGAIN forces execution to Jump unconditionally to the corresponding BEGIN*
There is no effect on the stack* Execution cannot leave this loop (unless R> DROP is
executed one level below)* At coMpile tine, AGAIN coMpiles BRANCH with an offset fro*
HERE to addr* n is used for coMpile-tiMe error checking*
II *Z Coin-Op FORTH Kernel* GIossbt^, p*8
Adds n bytes In nay be positive, negative, or zero) to the parameter field of the nost
recently defined word* Updates DP by n bytes ♦ Hay be used to reserve or delete
dictionary space*
— addr
A variable which contains the address of the entry in the disk buffer control table which
corresponds to the disk buffer least recently referenced (this buffer will be used to hold
the next source screen)*
nl n2 — r»3
Leaves the bitwise logical "and" of nl and n2 as n3.
This constant leaves the nuwber of bytes per disk block buffer* This is 1023 (IK) in
CoirrOp FORTH*
This constant leaves the nunber of blocks per editing screen* Conventionally* an editing
screen is 1023 bytes organized as 16 lines of 63 characters each* However, in Coin-Op
FORTH, an editing screen is 1023 bytes organized as 32 lines of 32 characters each, due to
the width of the Atari display screen*
addr —
Calculate the backward branch offset fron HERE to addr and conpile this offset into the
next available dictionary nenory address*
— addr
A user variable containing the current nunber base used for numeric input and output
conversion.
BEGIN — addr n (compiling)
Occurs in a colon-definition in fornt
BEGIN *** UNTIL
BEGIN .** AGAIN
BEGIN ♦*♦ WHILE *.♦ REPEAT
At run-tine* BEGIN harks the start of a sequence that nay be repetitively executed* It
serves as a return point fron the corresponding UNTIL, AGAIN or REPEAT. When executing
. UNTIL, a return to BEGIN will occur if the top of the stack is false} for AGAIN and REPEAT
a return to BEGIN always occurs.
At conpile tine BEGIN leaves the return address for UNTIL, AGAIN, or WHILE and n for
conpiler error checking on the stack.
TT *>
J — L ♦ j—
BFHD
n — addr (found)
n — f (riot found)
Checks to see if block n is already contained in a disk buffer which is Marked as "in
use". If it is, returns addr, which is the address of that buffer's entry in the disk
buffer control table (PTAB)* If not, returns a
BL
A constant that leaves the ascii value for "blank" ♦
BLANKS
addr n
Fills an area of memory beginning at addr with an ATASCII (value = 20) ♦
BLK
— addr
A User variable containing as the input stream the block, number being interpreted* If
zero, input is being taken from the terminal input buffer*
BLOCK
EfiANCH
n —
Leaves the memory address of the block buffer containg block. n« If the block is not
already in memory arid marked as being "in use", it is transferred from disk to whichever
buffer was least recently written, and that disk buffer is established as the "current"
buffer* If the block occupying that buffer has been harked as updated, it is rewritten to
disk before block n is read into the buffer* See also BUFFER, R/H UPDATE aiJSH*
The run-time procedure to unconditionally branch* An in-line offset is added to the
interpretive pointer IP to branch ahead or back. BRANCH is compiled by ELSE, AGAIN,
REPEAT * An in-line branch offset must follow any compiled instance of the ideogram*
BUFFER
C!
n — addr
Obtains the next memory buffer (indicated by ALT)*
is written to the disk*, the buffer is then
first cell within the buffer for data storage*
n addr —
Stores the least significant 8 bits of n at addr*
If the buffer is marked as updated, it
block n* The address left is the
n
Constant leaving the number
32*
of characters per FORTH screen line. For the Atari, this is
C
Stores the lower order byte of n into the next available dictionary byte, advancing the
dictionary pointer.
Glossary t p ♦
a?
3ddr — b
Leaves on the stack the contents of the byte* (The value on the stack will be 16-bit with
the high byte set to zero)*
CFA
pfa — cfa
Converts the parameter field address of a definition to its code field address*
CMOVE
addrl, addr2, n —
h bytes beginning at address addrl to address addr 2* The contents of address addrl
is moved first* proceeding toward high memory* If n is 0* nothing is moved* n must be
greater than or equal to 0 for this ideogram to function properly*
COLD
The cold start procedure to adjust the dictionary pointer to the minimum standard arid
restart via ABORT* Hay be called from the terminal to remove application programs and
restart* Cold start
"origin" ($D00) in memory*
COMPILE
CONSTANT
Nhen a word containing COMPILE executes, the 10-bit value following the compilation
address of COMPILE is copied (compiled) into the next available position in the dictonary*
i*e*, COMPILE DUP will' copy the CFA of DIP* COMPILE is usually used within immediate
words such as IF arid DOES>.
n
A defining word used in the form**
n CONSTANT cccc
to create a dictonary entry for cccc, with its parameter field containing n* When cccc is
later executed, n will be placed on the stack*
CONTEXT — addr
A user variable containing a pointer to the vocabulary within which dictionary searches
will begin during interpretation of the input stream*
COUNT
addr — addr+l n
Leaves the address and the character count n of the text beginning at addr* It is
presumed that the first byte at addr contains the text byte count arid the actual text
starts with the second byte* n ranges from 0 to 255* Typically COUNT is followed by
TYPE*
CR
Causes a carriage return arid line feed to occur on selected output device*
FORTH Kernel t Glossary * p*ll
CREATE
CSP
A defining word used in the form**
CREATE cccc
by such words as CODE and CONSTANT to create a smudged dictonary header for a FORTH
definition* The code field of the new word contains the address of the word's parameter
field. The new word is created in the CURRENT vocabulary*
addr
A user variable which can be used to store temporarily the stack pointer position, for
compilation error checking*
CURRENT — addr
A user variable which specifies to which vocabulary new word def initions will be added*
In dictionary searches, the CURRENT vocabulary is searched second, after the CONTEXT
vocabulary*
dl d2 — d3
Leaves the double number sum d3 of two double numbers dl arid d2*
D+-
dl n — d2
Negates the double number dl if n is negative*
Di
Prints the double number d, converted to ATASCII according to BASE, in a free field
„ with one trailing blank* Displays the sign only if negative*
d n —
Prints a signed double number d, converted to ATASCII according to BASE, right-aligned in
a field n characters wide* Displays the sign only if negative* If n=0, does not
right-align the value*
D8U*
dl, n — d2
Multiplies an unsigned double number dl by the unsigned 8-bit value n, leaving the product
as an unsigned double number d2*
DAES
dl — d2
Leaves the absolute value of a double number*
DDIO
n
Reads or writes 256 byte sector n on a double density disk* The read or write must be set
previous to entry to DDIO by setting the command byte of the device control block* The
buffer address for reading or writing must also by preset*, this address is incremented by
256 at the end of DDIO to prepare for reading or writing the next sequential sector*
♦ 2 Co ± n— Op FORTH
DECIMAL
Sets the numeric conversion base for input-output to ten*
DECHAP
nl ri2 - nl n3
Gives the logical sector number n2, returning the proper physical sector number n3 for use
with a single density 8" disk drive* nl=0 indicates a non-interleaved drive} nl=8000
irrdicates a DEC interleave drive*
DEFINITIONS
Sets CURRENT to the CONTEXT vocabulary* so that subsequent definitions will be added to
the vocabulary previously selected as CONTEXT* (Often used in the form**
cccc DEFINITIONS
where cccc is a vocabulary name)*
DIGIT
c nl — n2 tf (valid conversion)
c nl ff (invalid conversion)
Converts the ASCII character c (using base nl) to its binary equivalent n2, accompanied by
a true flag* If the conversion is invalid, leaves only a false flag*
DIO
n
Reads or writes 128 byte sector n on a single density disk* The read or write Must be set
previous to entry to DIO by setting the command byte of the DCB* The buffer address for
reading or writing must also be preset; this address is incremented by 128 at the end of
DIO to prepare for reading or writing the next sequential disk sector*
DUTERAL
d — d (executing)
d — (compiling)
If compiling, compiles a stack double number into a literal along with a run-time routine
(LTD* Later execution of the definition containing the literal will push it onto the
stack* If executing, the number will remain on
DMINUS
dl — d2
Converts dl to its double number two's complement.
Z Coin— Op FORTH Kernel, Glossary
D0ES>
DO nl n2 — (execute)
addr n (compile)
Occurs in a colorr-def initiori in form**
DO LOOP
DO ♦♦♦ +L00P
At ruri tif^e t DO begins a sequence with repetitive execution controlled by 3 loop limit nl
and an index with initial value n2« DO removes these from the stack. Upon reaching LCK3P
the index is incremented by one. If +L00P is used, the index is incremented by the value
on top of the stack* This value may be negative, i*e*, the loop nay run with its index
decreasing to a lower limit*, see +L00P) Until the new index equals or exceeds the limit,
execution loops back to just after DO*, when the index does equal or exceed the limit the
loop parameters are discarded and execution continues beyond loop* Both nl and n2 are
determined at run-time and may be the result of other operations* Both nl and n2 are
signed 16-bit values* Within a locp 'I' will copy the current value of the index to the
stack-.* See I, LOOP, +L00P, LEAVE* When compiling within the colon-definition, DP
compiles the run-time code (DO), leaves the following address addr arid n for later error
checking ♦
in conjunction with <BUILDS to create defining words* Used in the form!
*♦ cccc -(BUILDS ***D0ES> ♦♦♦ *,
It marks the terminator* of defining code arid the start of run-time code in cccc*
When cccc is executed in the form cccc hhhb, D0ES> alters the code field address and the
first parameter of bbbb so that, when bbbb is executed, the sequence of words following
DOES)- in cccc will be executed* (The PFA of bbbb will be on the stack when this exearlion
begins, allowing the parameters of bbbb to be used by the code following DOES)*
Ur addr
A constant which returns the address (or 0 page) of the dictionary pointer, which contains
the address of the next free memory above the dictionary* The value may be read by HERE
arid altered by ALLOT*
DPL addr
A user variable containing the number of digits to the right of the decimal on double
integer input* It may also be used to hold output column location of a decimal point, in
user generated formating* The default value on single number input is -1*
DRO —
DR1
Commands which select disk drives, by presetting OFFSET* DRO selects "drive 1"* DR1
should select "drive 2"} however, it actually selects "drive 3"* The contents of OFFSET
is added to the block number in EtOCK to allow for this selection* Offset is supressed
for error text so that it may always originate from the first drive*
DROP n —
Drops the top number from the stack*
II*Z Coin-Op FORTH Kernel* Glosssry, p ♦ 1^
DUP n — n n
Duplicates the top value on the stack*
I 0
ELSE addr nl — addr 2 n2
(compiling)
Occurs within a colon-definition in the formt
IF ♦ *. ELSE *♦* ENDIF
At run-tine, ELSE executes after the true part following IF* ELSE forces execution to
skip over the following false part arid resumes execution after the ENDIF* It has no stack
effect*
At compile-time ELSE compiles BRANCH and reserves space at addr2 for a branch offset which
will be resolved by ENDIF} it then leaves the address addr2 and n2 for error testing*
ELSE also resolves the pending forward branch from IF by calculating the offset from addrl
to HERE arid storing it at addrl*
EMIT
Transmits AT ASCII character c to the selected output device*
EMPTY-BUFFERS —
Marks all block-buffers as empty, without affecting the contents* Updated blocks are not
written to the disc* This is also an initialization procedure before first use of the
ENCLOSE addrl c —
addrl nl n2 n3
The text seaming primitive used by WOFD* From the text address addrl and an ATASCIE
delimiting character c* the following offsets are determined 4 *
nl is the offset from addrl to the first non-delimiter character
n2 is the offset from addrl to the first delimiter c after the text
n3 is the offset from addrl to the first character beyond addrl+n2
END
This is a synonym for UNTIL*
addr n — (compile)
Occurs in a colon-def inition in formt
IF *♦. ENDIF
IF .** ELSE ♦** ENDIF
At run-time* Dfl)IF serves only as the destination of a forward branch from IF or ELSE* It
marks the conclusion of the conditional structure* TI€N is another name for ENDIF* tath
names are supported in fig-FORTH* See also IF and ELSE*
At compile-time, ENDIF computes the forward branch offset from addr to HERE and stores it
at adr* n is used for error tests*
XI* 2 Coin— Op FORTH Kernel f GlossBfjf p ♦ 15
ERASE addr r» —
Sets n bytes, starting from addrl to 0*
ERROR line — in blk
Executes error notification arid restart of system* HARKING is first examined* If 1, the
text of line n, relative to lire 0 of screen 4 on drive 0 is printed* This line nuhber
way be positive or negative, arid hay lie beyorid screen 4* If HARNBIG=0, n is just printed
as a message number* If HARKING is -1, the definition (ABORT) is executed, which executes
the system AEtIRT* The user hay cautiously Modify this execution by altering (AKH\T)*
Fig-FORTH saves the contents of IN and BLK to assist in determining the location of the
error* Final action is execution of QUIT*
EXECUTE cf a —
Executes the definition whose code field address is on the stack* Different frow starting
FORTH, which takes pfa*
EXPECT addr n —
Transfers characters from the terminal to address, until a "return" or the count of n
characters has been received* Takes no action for n less than or equal to 0* One or more
nulls are added at the end of the text*
FENCE — addr
A user variable containing an address below which FORGETting is not allowed* To forget
below this point the user Must alter the contents of FENCE*
FILL addr n b —
Fills Memory starting at addr with a sequence of n copies of byte b* n>0*
FIRST — n
A constant that leaves the address of the first (lowest) block buffer*
FID — addr
A user variable for control of number output field width* Although defined, this ideogram
is not currently used by fig-F(FTH implementations*
FLUSH —
Hrites all blocks which have been flagged as updated to display arid mark them as "in use"
rather than "updated"*
11*2 Coin-Op FORTH Kernel, GlossBrs. p*16
Executed in the forn*"
FORGET cccc
Deletes word cccc froh the dictionary along wih all words added to the dictionary after
cccc, regardless of their vocabulary ♦ If cccc cannot be found in a search of the CONTEXT
and CURRENT vocabularies, or if cccc's definition lies below the address contained in
FENCE, an error message will be delivered* In addition an error message will ocd.it if the
CURRENT and CONTEXT vocabularis are not currently the sane*
The mm of the prinary vocabulary* Execution hakes FORTH the CONTEXT vocabulary* All
new definitions are added to the FORTH vocabulary until new vocabularies are created arid
established as the CURRENT vocabulary* Vocabularies conclude by "chaining" to FORTH, so
it should be considered that FORTH is "contained" within each of its descendant
vocabularies*
vl, addr, — v2
Given addr, the starting address of a mm string in nettory, arid vl the address of the
first sub-vocabulary entry pointer in a given vocabulary definition, returns v2, the
address of the sub-vocabulary entry pointer in that vocabulary which points to the proper
sub-vocabulary in which to search for an entry which hatches the nane string* In Coin-Op
FORTH, each vocabulary has been hashed into 8 sub-vocabularies dependent on the AT ASCII
value of the first character of a word's nane«
See VOCABULARY and the user Manual description of Coin-Op FORTH linking*
— addr
Returns the address of the next available dictionary location*
Sets the rower ic conversion base to sixteen (hexadecimal)*
— addr
A constant which returns the address of OS register HIMEN* This register contains the
address of the last byte before the Atari display list (hence, the last byte usable by the
dictionary)*
— addr
A user variable that holds the address of the latest character of text during numeric
output conversion*
c —
Used between <* and t> to insert an ATASCII character into a pictured numeric output
string* e*g* 2E HOLD will place a decimal point. (Output generation occurs frow high
fiewory to low nenory.)
— n
Used within a DO-LOOP to copy the loop index to the stack* Alias for R*
ELL
Coin~Op FORTH Kernel^ Glosssr^ » p ♦ 1Z
ICAL — addr
A constant which returns the address of the buffer address entry in TXB \ 0 (used by
keyboard and screen editor)*
ICCM — addr
A constant which returns the address of the connand byte in 1KB *0 (IOCB used by the
keyboard and screen editor ) ♦
A constant which returns the address of the buffer length entry in IOCB *0 (IOCB used by
the keyboard and screen editor)*
3D NFA —
Prints a definition's nane fron its nane field address*
IF f — (run-tine)
— addr n (compile)
Occurs in a colon-definition in the forni
IF (tp) ♦♦♦ ENDIF
IF (tp) ♦♦♦ ELSE (fp) •.♦ENDIF
At run-tine. IF elects execution based on a Boolean flag* If f is true (non-zero) ♦
execution continues ahead thru the true part* If f is false (zero), execution skips till
just after ELSE to execute the false part* After either part* execution resunes after
ENDIF i ELSE arid its false part are optional} if Kissing, false execution skips to just
after ENDIF*
At conpile-tine IF compiles OBRANCH and reserves space for an offset at addr* addr and n
are used later for resolution of the offset and error testing*
IMMEDIATE
Mark the nost recently nade definition as a word which will be executed when encountered
during compilation rather than conpiled (i*e* the precedence bit in its header is set)*
The user nay force conpilation of an innediate definition by preceeding it with (COMPILE)*
IN — addr
A user variable containing the byte offset within the current input text buffer (terninal
or disk) fron which the next text will be accepted. HORD uses and noves the value of IN*
nl n2 —
Prints the first line of each screen over the range nl, n2* This is used to view the
initial connent lines of an area of text on disk screens*
INPT — addr
A user variable which serves as the keyboard input buffer in Coin-Op FORTH*
2 Coin-Op FORTH
P ♦
INTERPRET
The outer text interpreter which sequentially executes or compiles text from the input
stream (terminal or disk) depending on STATE ♦ If a word name in the input stream cannot
be found after a search of CONTEXT and then CURRENT it is converted to a nwrtber according
to the current base* That also failing, art error message echoing the name with a "?" will
be given • Text input will be taken according to the convention for WORD* If a decimal
point is found as part of a number, a double number value will be left* The decimal point
has no other purpose than to force this action* See NUMBER*
Returns the current index of the next outer loop* Hay be used only within a nested
DO-LOOP structure*
KEY
LATEST
Leaves the AT ASCII value of the next terminal key struck* If the key was an EOL (RETURN),
a 0 is left on the stack, rather than $?B* ABORTs if the BREAK key is pressed*
— addr
Leaves the name field address of the most recently defined word in the CURRENT vocabulary*
Forces termination of a DQ-LOOP at the next LOOP or +LQQP by setting the loop limit equal
to the current value of the index* The index itself remains unchanged, and execution
proceeds normally until LOOP or +L00P is encountered*
pfa — lfa
Converts the parameter field address of a dictionary definition to its link field address*
LIMIT
LIST
n
A constant leaving the address just above the highest memory available for a disk buffer*
In CoirrOp FORTH, this is the beginning of the FORTH kernel (unlike other FORTHs, where
the disk buffers are high up in RAM)*
n
Displays the ATASCII text of screen n on the selected output device* SCR contains the
screen number during and after this process*
LIT
— n
Within a colon definition, LIT is automatically compiled before each 16 bit literal number-
encountered in input text* Later execution of LIT causes the contents of the next
dictonary address to be pushed to the stack*
II ♦Z Coin— Op FORTH Kernel , Glossars ^ p ♦ 19
LITERAL n — n (executing)
n — (compiling)
■
If compiling, then compile the stack value n as a 16 bit literal* This definition is
immediate so that it will execute during a colon definition. The intended use isi
J xxxx [calculate! LITERAL }
Compilation is suspended for the compile tihe calculatiori of a value. Compilation is
resumed arid a LITERAL compiles this value along with the rurrtime code LIT* If not
compiling, nothing happens arid n remains on the stack.
LOAD r. —
Read screen n from disk arid begin interpretation of it. If the word — > is encountered,
screen n+1 will be loaded arid interpretation will continue on it* If either the word *,S
or the end of a screen is encountered, interpretation will return either to the disk
screen on which LOAD was encountered (i*e*» LOAD can be nested) or to the terminal.
LOOP addr h — (compiling)
Occurs in a colon-definition in form!
DO ♦.. LOOP
At rurrtime, LOOP selectively controls branching back to the corresponding DO based on the
loop index and limit. The loop index is incremented by one arid compared to the limit* A
branch back to DO occurs until the index equals or exceeds the limit*, at that time, the
parameters are discarded and execution continues beyond LOOP.
At compile-time, LOOP' compiles the rurrtime word (LOOP) arid uses addr to calculate an
offset to DO* n is used for error testing*
Hx nl n2 — d
■
A mixed magnitude math operation which leaves the double number signed product of two
signed numbers*
d nl — n2 n3
A mixed magnitude math operator which leaves the signed remainder n2 arid signed quotient
n3, from a double number dividend d and divisor nl* The remainder takes its sign from the
dividend*
H/ttOD udl u2 — u3 ucH
An unsigned mixed magnitude math operation which leaves a double quotient ucH and
remainder u3, from a double dividend udl and a single divisor u2*
HAX nl n2 — max
Leaves the greater of two numbers*
II *Z Coin-Op FORTH Kernel, Glossary, P* 20
MESSAGE n —
Prints on the selected output device the text of line n relative to screen 4 of drive 0*
n may be positive or negative ■ MESSAGE nay be used to print incidental text such as
report headers* If WARNING is zero, the message will simply be printed as a number. (If
r. indicates a screen beyond screen 7 (ri>127), the text will actually be taken from line
n-256. Thus, when n=128, text will be taken fro* screen 2, line 0 instead of
line 0.)
KB) rd n2 — nin
Leaves the lesser of two rubers*
MINUS td — n2
Leaves the twos complement of a number ♦( Negates the number).
MOO nl n2 —
Divides nl by nZ t leaving the remainder n3 (with the sane sign as n2) .
*
NFA Pf a — nfa
Converts the paraneter field address of a definition to its nacie field address.
NUMBER addr — d
Converts a character string left at addr (with the count in the first byte) to a
double nuHberi using the current numeric base* If a decimal point is encountered in the
text, its position will be given in DPI, but no other effect occurs* If numeric
conversion is not possible, an error message will be given* The string must end with a
blank,*
OFFSET — addr
A user variable which hay contain a block offset to disk drives* The contents of OFFSET
is added to the stack, number by BLOCK. Messages printed by MESSAGE are independent of
OFFSET* See BLOCK, DRO, DR1, MESSAGE.
OR nl n2 — r»3
Leaves the bit-wise inclusive "or" (n3) of two 16 bit values (nl,n2).
OUT — addr
A constant which returns the address of the OS register COLCRS. This register contains
the horizontal position on the screen at which the next character will be put. The user
may alter and examine OUT to control display for hatting. OUT is incremented by EMIT.
OVER nl n2 — nl n2 nl
Copies the second stack, value, nl, placing it as the new top.
— addr
Leaves the address of the text output buffer, which is a fixed number of bytes above HERE<
This buffer is used as a "scratch pad" to hold characters for intermediate processing.
Its capacity is
* p ♦
1
PFA
nfa — pfa
Converts the name field address of a compiled definition to its parameter field address .
PHYSOFF — addr
A user variable containing the value added to the logical block * to obtain the physical
block * of a FORTH screen* This allows for "negative screens"* Used by various disk-
access words*
PREV
— addr
A variable containing the address of the entry in the disk, buffer control table (PTAB)
corresponding to the disk buffer most recently referenced. The IPDATE command narks this
buffer to be later written to disk*
PTAEi
QIERY
— addr
A variable whose parameter field contains the disk buffer control table* There are 4
entries in this table* each containing five bytes* The first entry contains information
on the disk, buffer containing the screen most recently accessed, while the second entry
contains information on the buffer containing the screen which was accessed before that*
The third or fourth entries are currently unused, as there are only two disk buffers} they
could be used if more than 2 disk buffers were desired* The first cell of each entry
contains the number of the screen contained in the block) the second cell contains the
starting address of the buffer*, the last byte contains the status of the buffer (0 = not
in use, 1 = in use, $81 = in use arid updated)*
Accepts input of up to 120 characters of tad (or until a "return") from the operator's
terminal* Text is placed in the terminal input buffer, whose starting address is
IN is set to 0*
QUIT
Clears the return stack, stops compilation, and returns control to the operator's
terminal* No message is given* This is the outermost word in FORTH*, it contains a loop
which continually waits for input and then invokes INTERFIO*
R
n
Copies the top of the return stack to the computation stack*
R*
— addr
A user variable which may contain the location of an editing cursor, or other file related
function*
addr blk f —
The fig-FORTH standard disk read-write linkage* addr specifies the source or destination
block buffer, blk is the sequential number of the referenced block, and f is a flag where
f=0 write and f=l read* R/W determines the location on mass storage, performs the
read-write and performs any error checking* The type of disk drive arid the drive * are
also indicated by blk} see the user manual for proper values*
XX * Z Co i n— Op FORTH Ker r.e 1 , Glossers #• p ♦ Z2
— addr
A user variable containing the initial location of the return stack* This ideogram is not
actually defined in Coin-Op FORTH* However, the proper value has been stored in the user
area at UP + 8 (see UP in the assembler glossary) arid the user can access it if necessary*
Removes the top value from the return stack and leaves it on the computation stack* See
/R and R*
addrl nl addr2 n2 — (compiling)
Used within a colon-def inition in the form**
BEGIN ♦*♦ HHILE *** REPEAT
At run-time, REPEAT forces an unconditional branch back to just after the corresponding
BEGIN*
At compile-time, REF'EAT compiles BRANCH and the offset fro* HERE to addrl* It then
compiles the forward branch offset from addr2 to HERE and stores it at addr2 (resolving
WHILE)* nl and n2 are used for error testing*
nl n2 n3 — n2 r»3 nl
Rotates the top three values on the stack, bringing the deepest to the top*
Initializes the return stack pointer from user variable RO* (RO is not directly
accessible to the user)*
n — d
Extend a signed single number to form a signed double number.
— addr
A user variable which contains the initial value of the stack pointer* This ideogram is
not actually defined in Coin-Op FORTH and as such is not directly accessible to the user*
However, the proper value has been stored in the user area at UP + 6 (see UP in the
assembler glossary) arid the user can access it if necessary* It is useful for judging the
depth of the stack and for setting up non-destructive stack dumps*
Pronounced S-zero* See SP!*
— addr
A user variable containing the screen number most recently listed* This is used by
various screen editing functions*
n —
Sets up the device control block to indicate a disk I/O operation should be performed on
disk sector n, arid then executes SIO* If SIO returns an I/O error condition* an error
message is sent to the terminal and ABORT is executed* Expects the command byte, buffer
address arid length, and device ID * to be already set in the device control block*
XI* 2 Coin-Op FORTH Kernel*
SIGN
n d — d
Stores an AT ASCII sign just before 3 converted numeric output string in the tort
output buffer When n is negative* n is discarded, bid double nunber d is maintained*
Host be used between <* and #> (just before *)•
SIO
0 — - n
Executes the Atari SIO (serial input/output) routine* Assumes that the device control
block is properly set up* SIO is used for disk access* It returns n, where n=0 indicates
no error occurred dur ing SIO, and n>0 indicates that an error * n+1 occurred during SIO*
SHUDGE
Used during word definition to toggle the "swudge bit" in a definition's name field*
Setting this bit prevents an uncompleted definition from being found during dictionary
searches, until compiling is completed without error* Orice the bit is set to zero, the
definition can be found in searches* (NOTE! This allows the possibility of recursive
definitions*)
SP!
SPACES
Initializes the stack pointer fro* SO* (SO is not directly accessible to the user. See
SO*)
— addr
Returns the address of the top of the stack, as it was just before SPB was executed.
Transmits an ATASCIE blank to the output device*
n
Transmits n ATASCII blanks to the output device* Takes no action if n=0*
STATE
aoor
A user variable containing the compilation state* A non-zero value indicates compilation,
while a value of 0 indicates execution*
SWAP
TASK
nl r*Z — ri2 nl
Exchanges the top two stack values*
A no-operation word which narks the boundary between the Coin-Op FORTH boot and
applications*
II * 2 Co i n— Op FORTH Ker ne 1 1 Glossary * P ♦ 2^
— b f
n — n b f
Executes a call to CIO (the Atari central Input/Output routine) using IOCB * 0. Asswes
that IOCB * 0 has been properly set up for whatever operation is desired* If the buffer
length cell in IOCB is set to 0 on a "put" operaton, the top value on the stack, will be
sent to the device (through the accumulator) but it will not be removed from the stack.
The routine returns the value $80 if a break was encountered during the CIO routine}
otherwise it returns a 0, Do not use interactively*
THEN
An alias for ENDIF*
TIB
— addr
A user variable
input buffer*
IM!
addr b —
Complements the 8-bit contents of addr by the bit pattern of byte b*
TRAVERSE
addrl n — addr2
Moves across the name field of a fig-FORTH variable length name field* addrl is the
address of either the length byte or the last letter* If n=l, the motion is toward the
end of the name? if n=-l, the motion is toward the length byte* The addr 2 resulting is
the address of the other end of the name*
scr
Displays on the selected output device the three screens which include that numbered scr,
beginning with a screen evenly divisible by three* Output is suitable for source. text
records, arid includes a reference line at the bottom taken from line 15 of screen 4*
TYPE
addr n —
Transmits n characters starting at addr to the screen* No action occurs if n=0* Vectors
to AESJRT if the break key is pressed.
ul u2 — ud
Performs an unsigned Multiplication of ul by u2, leaving the unsigned double number
product ud.
U/
ud ul — u2 u3
Leaves the unsigned remainder u2 and unsigned quotient u3 from the unsigned double
dividend ud arid unsigned divisor ul.
IK
ul u2 - f
Leaves a true flag if unsigned 16 bit value ul is less than unsigned 16 bit value u2*,
otherwise leaves a false flag.
XI ♦ 2
Kernel f Glossar^ » p*
UNTIL
f — (run-time)
addr n — (compile)
Occurs within a colorr-def inition in the form**
BEGIN ♦ ** UNTIL
UNTIL Marks the end of a BEGBHMIL loop, At run-time, UNTIL controls the conditional
branch back to the corresponding BEGIN* If f is false , execution returns to just after
E£GIN; if true, execution continues beyond UNTIL •
At compile-time, UNTIL compiles the run-tine ( OBRANCH ) arid an offset fro* i-
n is used for error tests*
E to addr*
UPDATE
Harks the most recently referenced block (pointed to by PREV) as modified ♦ The block will
subsequently be transferred automatically to disk should its buffer be required for
storage of a different block, or upon execution of FLUSH*
USER
A defining word used in the for***
n USER cccc
which creates a user variable cccc* The parameter field of cccc contains n which is the
cell offset relative to the user pointer (register UP) for this user variable* When cccc
is later executed* it places the absolute user area storage address for cccc on the stack?
it is at this address that cccc's "value" is kept*
VARIAEtE
MUST
A defining word used in the form!
n VARIABLE cccc
When VARIABLE is executed, it creates a dictionary for cccc and allots 2 bytes in cccc's
parameter field for storage} the contents of these 2 bytes is initialized to n* Hhen cccc
is later executed, the address of its parameter field (containing n) is left on the stack,
so that a fetch or store nay access this location*
Lists the names of the definitions in the CONTEXT vocabulary* "Eireak" will terminate the
listing* The listing will continue into the CONTEXT vocabulary's parent vocabulary* (See
the user manual section on the linking system*)
VdC-LBK
A user variable containing the address of the vocabulary link field in the definition of
the most recently created vocabulary* All vocabulary names are linked by these fields to
allow control for FORGETting through multiple vocabularies*
♦ 2 Coin-Op FORTH Kernel , Glossary , p »26
VOCABULARY —
A defining word used in the form**
V0CAE1LARY cccc
to create a vocabulary definition cccc* Subsequent execution of cccc will hake it the
CONTEXT vocabulary which is searched first by INTERPRET* The seqier.ce "cccc DEFBaTEONS"
will also nake cccc the CURRENT vocabulary into which new definitions are placed*
In fig-FORTH, cccc will be so chained as to include all definitions of the vocabulary in
which cccc is itself defined (a "child/parent" relationship is thus establihed between
cccc and the vocabulary in which it is defined)* All vocabularies ultimately chain to
FORTH ♦ By convention* vocabulary names are to be declared IMMEDIATE* See UOC-LINK* See
the user manual for a description of the stricture of a vocabulary definition*
WARNING — addr
A user variable containing a value controlling messages. If = 1 then error messages are
taken from disk* arid screen 4 of drive 0 is the base location for messages* If = G*
messages will be presented by number* If = -li executes (AP-ORT) for a user specified
procedi.fr e* See MESSAGE* ERROR*
WHILE f — (run-time)
addrl ml — addrl nl addr2 n2 (compile-time)
Occurs in a colon-definition in the form**
BEGIN *** WHILE (tp) **♦ REPEAT
At run- timet WHILE selects conditional execution based on boolean flag f* If f is true
(non-zero), WHILE continues execution of the true part through to REPEAT, which then
branches back to BEGIN* If f is false (zero), execution skips to just after REPEAT*
exiting the structure.
At compile time, WHILE compiles OBRANCH and leaves addrZ of the reserved offset* The
stack values will be resolved by REPEAT. nZ is used for error checking*
WIDTH — addr
A user variable containing the maximum number of letters saved in the compilation of a
definitions' name. It must be 1 thru 31* with a default value of 31* The name character
count and its natural characters are saved, up to the value in WIDTH. The value may be
changed at any time within the above limits.
WORD c —
Reads the next text character from the input stream until a delimiter c is found, and
stores the packed character string beginning at the dictionary buffer HERE* WORD leaves
the character count in the first byte at HERE, then leaves the characters, and ends with
two or more blanks* Leading occurrences of c are ignored* If BLK is zero, text is taken
from the terminal input buffer, otherwise from the disk block whose number is stored in
BLK. See BLK, IN*
X —
This is a pseudonym for the "null", i*e* a dictonary entry for a name of one character of
AT ASCII null. It is the execution procedure to terminate interpretation of a line of text
from the terminal or within a disk buffer, as both buffers always have a null at the end.
XI*2 Coin-Op FORTH Kernel, Glossary, P*27
XOR nl rtZ — r»3
Leaves the bitwise logical exclusive-or (ri3) of two values (nl 9 nZ)«
Used in a colon-definition in form**
♦ xxx C words 3 wore J
Ends compilation arid sets the execution node* The words after C are executed, not
compiled* (This allows the user to perform calculations or make compilation exceptions
before resetting compilation with ]♦) See LITERAL, ]♦
[COMPILE] —
Used in a colon-definition in form**
- ! xxxx [COMPILE] FORTH }
[COMPILE] will force the compilation of an immediate definition, which would otherwise
execute during compilation* The above example will select the FORTH vocabulary when xxxx
executes, rather than at compile time*
] —
Sets the compilation mode 4 , text from the input stream is subsequently compiled* See [.
II + 3 A*t,3r± extensionst p ♦ 1
This section includes about ninety words, which can be divided into five groups J Graphics arid
sound words, controller arid player/missile graphics words, IOCB words, words from the DEC User's
Group, and a few Miscellaneous words* Source code for host of these words is included on the Coin-Op
FORTH boot disk for the user's convenience; the words are already in the boot, however* (The source
code is in highly compressed form and is best used with the formatted printer words, Section KM*)
The following discussions are aimed at familiarizing the user with the main words in this
section* Some of the words are not discussed, however, so browsing through the glossary, which is
complete, could be quite worthwhile*
Graphics arid Sound
Graphics ^
Read chapter 9 of the Basic Reference Manual (Graphics Modes and Commands) and chapter 3 of De
Re Atari (Graphics Indirection arid Character Sets); the latter will give you an idea of how color
registers work, while the former lists the specific Atari graphics commands* Coin-Op FORTH uses the
same graphic commands as Atari BASIC (using post-fix notation, of course! )♦
The main graphic commands are as follows**
GRAPHICS GR*
t COLOR C*
DRAWTO DR.
LOCATE LOC*
F10T PL*
POSITION POS*
PUT , GET
SETCOLOR SE*
XI01S
See the glossary for an explanation of how these words work in Coin-Op FORTH* The glossary also
contains graphics primitives and a number of constants which return the addresses of OS and hardware
graphics registers*
Sound
■
Read chapter 10 (Sound) of the Basic Referene Manual and chapter 7 (Sound) of De Re Atari for an
explanation of sound on the Atari*
The only Coin-Op FORTH sound word is SOUND, which operates exactly like the BASIC command except
that it uses post-fix notation* See the glossary entry below*
Controllers and Player /Missiles
Controllers
Read chapter 10 (section on controllers) in the Eiasic Reference Manual for a discussion of
controllers*
Coin-Op FORTH uses the controller words'.
PADDLE
PTRIG
STICK
STPJG
These work like their BASIC counterparts* See the glossary entries below for an explanation* Note
also that the constant CONSOL returns the address of the register which reads the START, SELECT, and
OPTION buttons.
Player/Hissiles
Read chapter 4 (Player - Missile Graphics) of De Re Atari for an emanation of how players arid
Missiles work*
Coin-Op FORTH includes the following player /Missile wordst
COLPti! - sets the color of a player
KTOS! - sets the horizontal position of a player or Missile
PBASE - returns the base address of player/Missile DMA
SIZE! - sets up player/Missile graphics*
In addition, the following constants return the addresses of registers which are useful in
Manipulating player /Missiles (consult the Atari OS and Hardware Manuals for an explanation)'*
DMACTL, GRACTL, PRIOR.
Consult the glossary below for descriptions of how to use these words.
Creation of the actual player/Missile (through storing values into player/Missile MeMory) is
left to the user, who will no doubt find C! and OWE (in the Coin-Op FORTH kernel) to be very useful
comands*
IOCB WORDS AND CIO
These words are used to set up I/O control blocks! these blocks in turn are used to perforM I/O
with a variety of devices. Ho atteMpt will be Made here to describe in detail the various devices,
coMMands, arid forMats used in this process. The user should read De Re Atari chapter 8 (Operating
SysteM) and the OS Manual section on I/O in order to gain such knowledge.
I/O is perforMed by setting up an IOCB (there are 10 of theM, each with 16 bytes) and executing
the OS CIO routine. Coin-Op FORTH facilitates this process by providing the user with a number of
words with which to handle IOCBs.
First, the user selects an IOCB #n to operate on by executing
n IOCB
where n is the nuMber of the IOCB which is to be used. The words ICDNO , ICCOM , ICSTA , ICBAL ,
ICBLL , I1CAX , I2CAX , AND ICPTL will then return to the user the addresses of various entries in
IOCB * n. For example, 0 IOCB I1CAX will return the address of the first auxiliary information byte
in IOCB *0 (which handles the screen editor)} 3 IOCB ICBLL will return the address of the buffer
length cell in HSCB *3.
These addresses can then be used to set up the IOCB. I4hen this is eonplete, execution of the
II ♦ 3 Atar i e>ct,eri^ i oris * p ♦ 3
word CIO will perform the desired I/O operation* (A related word, AGIO, is used in certain
circumstances to send a single character to a device through the 6502 accumulator J see the
glossary*) OPEN and CLOSE nay be used to open and close the currently selected IOCBJ PUT and GET
will put and get characters to arid from the device specified by the current IOCB*
DECUS
These words were written by the DEC Users Group, and perform some useful operations*
OSET sets a memory location to 0*
1+! , 1- , arid 2* do exactly what me would expect*
ALLOC functions like ALLOT, but it reserves cells rather than bytes* ARRAY and TBL are defining
words used to create tables* See the glossary for details*
BDUrF arid \ are used in conjunction with each other*
addrl addr2 BDUMP
will cause 2 digit hexadecimal representations of the contents of each byte from addrl to addr2 to be
placed on the screen* The routine places the first 8 values on one screen line, then performs a
carriage return arid places the next 8 on the next line, and so on* At the start of each line, EOUMP
also prints the address (in hexadecimal) of that line's first byte, arid at the end of each line the
routine points the FORTH word \ ♦ V f '.in turn, takes an address arid 8 values on the stack -
precisely the format in which BDUMP has printed out its data* \ then takes the low byte of each
value arid stores it into Memory, starting at the address on the bottom of the stack* It ends with a
QUIT, which performs a line-feed without printing out "oK"*
Thus, it is possible to make use of the Atari screen editor to move the cursor over a line which'
BDUMP has printed out and type over the values which are printed on that line 4 , when a [RETURN] is
then performed, these values will be written into memory at the locations which were read by BDUMP*
Furthermore, data printed by BDUMP on subsequent screen lines will not be damaged by n oK n s, since
QUIT is used to exit* This is a clever and powerful interactive tool* try it for yourself to see how
it works*
Miscellaneous
These include a number of OS and hardware constants (i*e*, constants which return the addresses
of OS and hardware registers), the historically obsolete constants LPWORDS arid FORMY (used to
indicate where the screen code of printing and code formatting words lay on disk), arid the word
SAVENFAs,
Read through the glossary to discover which OS arid hardware constants are available - these are
quite useful t and most of them are used by various graphics routines*
SAVENFAs takes the vocabulary entry pointers stored in the F01\TH vocabulary and saves them in
the boot parameter area (the 30 or so bytes after the "origin" , which is at $D00)1 This will
prevent a cold start (see COLD) from "forgetting" any non-booted words which the user has added. It
is used by HTOBJ*
♦IOC
A defining word used in the form*"
n *I0C cccc
Creates a header for cccc and places the value n in cccc's parameter field* When cccc is
later executed it returns the address of the memory location which is n bytes above the
first byte of the "current" IOCB. See IOCB*
OSET
addr —
Sets the 16-bit value at addr to 0»
1+!
addr —
Increments the 16-bit contents of addr by 1«
1-
n — n-1
Subtracts 1 fro* n.
2*
nl - n2
Hultiplies nl by 2* leaving the product n2*
ACIO
Places n in the 6502 accumulator arid calls CIO, which will use the I(X8 previously
selected by the user (see IOCB)* Assumes that the IOCE; is already set up* Can be used to
send a single character to a device* Normally used with ICBLL set to zero*
ALLOC
n
Reserves n cells in the dictionary (i*e* t advances the dictionary pointer by 2n bytes)*
ARRAY
A defining word used in the form**
n ARRAY cccc*
Creates a dictionary entry for cccc arid reserves n cells (n*2 bytes) as cccc's parameter
field* Later execution of cccc returns the address of the first cell in this parameter
field* This address may then be used to store and retrieve values in the parameter field*
ATACHR
— addr
A constant which
written to the
the AT ASCII value of the character most recently read from or
or the value of the most recently plotted or read color pixel*
AUDCTL
— addr
A constant which contains the address of the audio mode control register
BOTSC
— addr
A constant which contains the address of the split screen register ($2BR* If the
contents equal 4* split screen text is enabled; if they equal 23* full screen text is
enabled*
II * 3 Atr3r i E^teris i ons * Glossary * p ♦ Z
BDUMP addrl addr 2 —
Displays the contents of memory addresses addrl through addr2, byte by byte, on the output
device* The contents are displayed in a 2 digit hexadecimal representation* with 8 values
per screen line} the address of the first byte on a given line is printed at the beginning
of that line, arid each line ends with the word \, which allows memory locations in the
"dumped" area to be easily altered* See \ arid the user manual section on DECUS words*
C* n —
Sets the color register (pixel data to be used in subsequent plotting* drawing* and
printing) to n* n ranges from 0 to 4*
ClAUD — addr
A constant which contains the address of the audio control register for audio channel 1
($D20D*
C2AUD — addr
A constant which contains the address of the audio control register for audio channel 2
($D203)*
C3AUD — addr
A constant which contains the address of the audio control register for audio channel 3
($D205h
.
C4AUD — addr
A constant which contains the address of the audio control register for audio channel 4«
($D207)
CH — addr
Returns the address of the register which contains the ATASCII value of the most recently
pressed key* ($2FD*
CH? addr —
Converts the 8-bit contents of addr to a 2 digit hexadecimal value* and sends this value
to the output device*
CHBAS — addr
A constant which contains the address of the register which contains the most significant
byte of the starting address of the current character set* ($2H)*
CIO
cm n —
Types the least significant byte of n as a 2 digit hexadecimal number* (E*g* $0014 CHH
types 14} $FF23 CHH types 23)*
Calls the Atari CIO routine, using the "current" IOCB* This assumes that an IOCB has been
selected using n IOCB and that IOCB *n has been set up properly* (This can be done using
the words defined by *I0C, after n IOCB has been executed)*
CLEAR
Clears the screen*
XI ♦ 3 A t ar i Ex-Lens i ons * CIossbfh * P ♦ 3
CLOSE
* -
Closes the currently selected IOCB. n IOCE: Must be performed before calling CLOSE* Do
not attempt to close IOCB * 0, as this controls the screen editor*
CN n —
An alias for CONSTANT.
COLO — addr
A constant which contains the address of the playfield color register for playfield color
0. <$2C4)*
COL1 — addr
A constant which contains the address of the playfield color register for playfield color
U (*2C5)
C0L2 — addr
A constant which contains the address of the playfield color register for playfield color
2* ($2C6)*
C0L3 — addr
A constant which contains the address of the playfield color register for playfield color
3* <$2C7)*
COL4 — addr
A constant which contains the address of the playf ield color register for playfield color
4. (*2C8)*
Alias for C.
COLPM — addr
A constant which contains the address of the first player /nissile color register (i.e*,
the byte corresponding to player 0)* ($2C0)*
COLPH! c n —
Sets the color of player n to c, where the highest 4 bits of c indicate the color (0-15)
and the lowest 4 bits indicate the luminance (0-15, although the lowest bit is not
actually read so that luminances 0 and 1 are the same, as are 2 and 3, etc*)* n=0 to 3*
Missile tn will have the sane color as player#0, and so forth* unless the "five player"
option is enabled* See De Re Atari*
CQNSQL — addr
A constant which contains the address of the register which reads the console switches
START, SELECT, OPTION. ($D01F)
CRSINH — addr
A constant which contains the address of the cursor inhibit register ($2F0)* When the
contents equal 0, a cursor is displayed on the display screen.
XI * 3 At,3r i Excteris i oris * Glossary #- p ♦ *\
Color
— addr
A variable which contains the nunher of the color register to be used in drawing and
printing*
DLST
— addr
A constant which contains the address of the OS shadow of the register which contains the
starting address of the display list* ($230)*
DMACTL
— addr
A constant which contains the address of the OS shadow of the DMA control register*
($22F)* Alias for DMCT*
DMCT
— addr
A constant which contains the address of the OS shadow of the DHA control register*
($22F)*
DR*
X y —
Draw a line frow the ojrrent cursor position to x*y* in the color previously selected
(using SETCOLOR and COLOR)*
DRAWTO
F1AUD
Alias for DR*
addr
A constant which contains the address of the audio frequency control register for audio
channel 1* ($D200)*
F2AUD
— addr
A constant which contains the address of the audio frequency control register for audio
channel 2* ($D202)*
F3AUD
F4AUD
— addr
A constant which contains the address of the audio frequency control register for audio
channel 3* <$D2(W)*
addr
A constant which con tains the address of the audio frequency control register for audio
channel 4* ($0206)*
FILDAT
— addr
A constant which contains the address of an OS register
operations*
which holds data used in fill
XI ♦ 3 A t sr i Extent i ons t Glossary * p ♦ 5
FORMY
— 39
Returns decimal 39, which historically was used as the starting screen of a code
formatting program ♦
GET
Gets one character from the device specified by the "current" IOCB and leaves it on the
stack. Assumes that the IOCB is set up (except for the command byte) prior to the call to
GET*
GR.
n
Clears the current screen, opens the graphics screen using graphics mode n. Add decimal
16 to n to allow full screen graphics (i.e>i no text window*, this can only be used during
program execution when no screen editing functions are necessary). Add decimal 32 to n to
prevent the screen from being cleared.
GRACTL
addr
A constant which contains the value of the graphics control register. ($D01D).
GRAPHICS
n —
Alias for GR.
Get
n
A machine code routine which gets one piece of informaton from the device specified by the
"current" IOCB arid leaves it on the stack. The IOCB must be set up before Get is called.
H?
addr —
Converts the 16-bit contents of addr to a 4 digit hexadecimal value, and transmits this
value to the output device.
HD
n -
Types the single character representation of n, as if BASE were set to n+1 (e.g. 5 HD
types 5, 15 HD types F, 35 HD types Z).
HH n —
Converts the 16-bit value n id 3 A digit hexadecimal value, and transmits this value to
the o«.rtpLit device.
HPOS! H n —
Sets the horizontal position of player n to x. n = 0 to 7 (missile 0 = player etc.).
x = 0 to 255.
XI ♦ 3 At,3r i Extens i ons t Glossary * P ♦ «£
— addr
Defined by *I0C*
"current" IOCB*
Returns the address of the first auxilliary information byte in the
I2CAX
— addr
Defined by *I0C* Returns the address of the second auxilliary information byte in the
"current" IOCB*
ICBAL
— addr
Defined by *I0C* Returns the address of the low byte of the buffer address entry in the
"current" IOCB*
ICBLL
— addr
Returns the address of the cell which contains the buffer length entry in the "current"
IDCB.
ICCOM — addr
Defined by ♦IOC* Returns the address of the coward byte of the "current" IOCB*
ICDNO
addr
Defined by *I0C* Return the address of the device * byte of the "current" IOCB*
ICPTL
— addr
Defined by *I0C* Returns the address of the "put character entry pointer" in the
"Djrrent" IOCB* This is only used by BASIC*
ICSTA
— addr
Defined By *I0C* Returns the address of the status byte of the "current" IOCB*
IOB
— addr
A variable which contains an off set from the first byte of IOCB * 0 to the first byte of
the IOCB which is currently selected* See IOCB*
IOC
A variable which contains the starting address of the IOCB ojrrently selected by the user
^.0 i~ i ♦
IOCB
n —
Sets the "current" IOCB to IOCB * n*
(This changes the values in IOC and IOB)*
LHARGN
— addr
Constant which contains the address of the register which contains the left margin value
($52)*
NOPLY
II * 3 Atar i Extens i ons * Glossary t p ♦ T
LOC* x a — n
Gets the value of the pixel on the screen at position x,y, arid positions the graphics
cursor at this point* n will indicate which color register the pixel's color is taken
LOCATE x 3 — H
Alias for LOC*
LPWORDS — 37
Historically, line printer words were placed on screen 37 (decimal)} LPHORDS returned the
starting screen nunber so one could write LPHORDS LOAD*
Disenables player/ttissile DMA arid sets the player/ttissile size and position registers to
0* (This does not stop the player /Missile DMA cycle steal, however, as DMACTL is left
intact • )
OPEN nl n2 n3 —
Opens the "current" IOCB, using the pararteters on the stack* nl is the value to he stored
in ICAX2, n2 is the value to he stored in ICAX1, and n3 is the buffer address (the buffer
should contain an AT ASCII string by which CIO will identify which device is being linked
to the I0CB in question 4 , see the Atari OS Manual for details)*
PADDLE nl — n2
Reads paddle nl (nl = 0 to 7), returns paddle position n2 (n2 = 0 to 256)*
PBASE
Returns the address of the player/Missile DMA area* This value is set by GRAPHICS and
changes with different nodes*
PL* x y —
Plots a point in the color last selected (using SETCOLOR and COLOR cottnands) at screen
position x,y*
F1AYER n —
Sets up player /Missile DMA (by setting PBASE, GRACTL, and DMACTD* n = 1
resolution; n=2 for double line resolution* See De Re Atari*
F10T x y —
Alias for Fl*
SAMENFAs
II * 3 Atar i Ex-tens i ons * Glossary t p ♦ 8
PMBASE — 3ddr
A constant which contains the address of the hardware register which holds the most
significant byte of the base address of the player /missile DHA area* ($DW)*
POSi k a —
Sets the current graphics cursor position to x,y* (0,0 is the top left corner of the
screen) ♦ Does not plot any points*
POSITION x y —
Alias for POS*
PRIOR — addr
Returns the address of the hardware priority register (GPRIORJ $DW8)#
PTRIG nl — n2
Reads paddle trigger nl (nl = 0 to 7), returning n2 where n2 = 0 indicates trigger-
pressed, ri2 = 1 indicates trigger not pressed*
PUT n —
Puts the character with ATASCII value n at the current cursor position on the screen*
Qhase — n
A variable which contains the address of the player /missile base* See De Re Atari,
Returns a random number n on the stack, where n ranges from 0 to 255* (This value comes
from hardware timer SKRES)*
— addr
Returns the address of the first byte of system timer 1 ($14). This is a three byte
timer ♦
St — addr
A variable which contains the ATASCII characters "S" and n l n $ The address of this
variable is used as the buffer address in an "open" call to CIO and indicates that the
device being opened is the graphics screen*
tfoves the NFAs in the vocabulary entry pointers of the FORTH vocabulary to the boot
parameter area (starting at $D22)J after this is done, a cold start ( COLD ) will not
erase any words defined prior to the execution of SAVENFAs from the dictionary*
XI* 3 Atari Extensions. Glossary, p.?
SPB
SE* fli n2 n3 —
Sets color register nl+1 to hold color n2 with luminance n3.
SETCOLOR Til n2 n3
Alias for SE.
SIZE! s n —
Sets the width of player n to s, where s = 0 or 2 indicates normal width, s = 1 indicates
double width, and s = 3 indicates quadruple width* n = 0 to 4} all Missiles are set by n
= 4.
SKCTL — addr
A constant which contains the address of the serial port contol register ($D20F) which
controls the configuration of the serial port as well as the Fast Pot Scan arid the
Keyboard Enable Functions*
SOW© n p d v —
Sets audio channel n (n = 0 to 3) to have pitch p (p is actually a divisor*, see the Basic
Reference Manual for pitches corresponding to a given p), distortion d, and vol we v#
Sets the base address of the player/Missile DMA area and HIMEM (the highest available
dictionary address, which is $17F bytes above the player /fissile base address)*, the PM
base address nust fall on a 2K boundary*
STICK nl — n2
Reads joystick nl (nl = 0 to 3) and returns n2, where n2 indicates which direction the
stick is being pushed* See the Basic Reference Manual for these values.
STRIG nl — r»2
Reads joystick trigger nl (nl = 0 to 3) arid returns n2, where n2 = 0 indicates trigger
pressed and n2 = 1 indicates trigger not pressed*
A defining word used in the for***
TBL cccc nl , ri2 , n3 , ♦♦♦
TBL creates a header for "table" cccc*, values nay then be stored into cccc's parameter
field* When cccc is later executed, its PFA is returned on the stack, allowing the user
to then index values in the parameter field* Used to create date tables at compile tine*
3 Atsr x Extent i ons , Glossary , p * 10
«
VDELAY — addr
A constant which contains the address of a hardware register which is used to "delay" the
appearance of a player or missile by 1 scan line* This is useful when two-line player
resolution is used* ($D016)*
XI018 n —
Fills an area of the screen using the color in color register n«
in the Basic Reference Manual ♦
• )<-p
\
addr nO nl h2 ri3 xA rfi n6 n7
Takes the low byte of each stack value nO , nl i ♦ ♦ ♦ t n7 » and stores those bytes in memory
beginning at addr* nO is stored at addr+O* nl is stored at addr+l, etc* This is used in
conjuncton with BDUMF" to facilitate rapid alteration of the contents of an
See BDUHP arid the discission of DECUS words before this glossary*
II The Fig Editor, p,l
II.4 THE FIG EDITOR
The usual way of entering the fig Editor is by using n EDIT, which sets up editing on screen n*
The cowand words in the fig Editor can be divided into three groups'* screen editing words, line
editing words, and words frow the FORTH vocabulary that are useful for editing* The conaands in
these three groups are listed below?
Screen Editing Cowhands
UL LL DOIT
Line Editing Demands
HL DL IL RL CL SL SL TL * 1
Other Dottnartds
L N COPY SHOW LIST WHERE
The cursor control (arrow) arid editing (Clear, Insert, Delete) keys are also used in the fig Editor ♦
Screen Editing Words
There are three screen editing words in the fig Editor: UL and LL clear the display screen and
list the 'upper' or 'lower' (first or last) 16 lines of the current screen. The third word, DOIT,
causes the contents of the top 16 lines of the display screen to be copied to the appropriate half of
the screen buffer and Marks that buffer as updated* For convenience, UL and LL print the word DOIT
two lines below the 16 lines that they list* To use the screen editor, do a UL or LL (depending on
which half of the current screen you want to work on) , then use the arrow arid editing keys to change
the information on the top 16 lines of the display* When you are finished editing that half-screen,
register the changes by moving the cursor to the line with DOIT on it and hitting [RETURN] ♦ An
Important Note: don't hit [RETURN] while you are on the top 16 lines of the display* If you do, the
interpreter will try to interpret the stuff you are editing* Use the arrow keys to move from line to
line instead*
Line Editing Words
Most of the fig line-editing cow-ends involve nerving lines back and forth between the current
screen and the pad* IL, DL, HL, RL, and CL all fall into this category (thou* CL copies a specified
line from another screen to the pad)* SL and BL put a blank line on the current screen, but in two
different ways** SL Moves the lines below the new blank line down to hake roott for it, while El just
overwrites the specified line with blanks* % and % both put the text following then onto the screen 4 *
$ puts it on the specified line} I puts the text on the line after the specified line, pushing the
lines below it down to wake rooM* TL sets up editing of a specified line by typing the line with the
line nuriber and a $ preceding it (it also copies the line to the pad)* This way, you can TL a line,
edit it with the arrow keys, and put the edited line back by just hitting [RETURN] (since the line
nunber and % are already there) ♦
Except in certain situations (inserting lines onto a screen that already has text on it, for
example), the line editing cowards are not as useful as the fig screen editor, since moving a cursor
around and. waking changes on the screen are easier than typing lots of corwands*
XX* 4 The Fie Editor, p*Z
Other Editing Words
There are also some words trtm the FORTH vocabulary that are useful for editing* LIST and SHOW
are good for looking at one or wore screens (to find a certain word, for example)* COPY, as its name
implies, copies the contents of one screen to another* L lists the current screen* N lists the next
screen* WHERE is useful for finding errors in a screen that won't LOAD* Typing WHERE after
compilation halts will print the screen number and the text of the line where the compiler stopped,
with a caret indicating exactly where the error was found*
The normal way of exiting the fig Editor is with FLUSH, which resets the screen margins, copies
updated screens to disk, and puts the system back in the FORTH vocabulary*
♦OFLBCS — r.
Returns the number of lines per editing screen (32) *
-MOVE addr n — EDITOR
Moves a line of characters that starts at addr to line n of the current edit screen*
Marks the current screen as updated*
$ n — EDITOR
Puts the text following $ on line n of the current edit screen* Marks the screen as
updated*
7. n — EDITOR
Puts the text following % after line n of the current edit screen* The lines below line n
are pushed down to make room (the last line of the screen is lost)* Marks the screen as
El n — EDITOR
"Blank lire*" Replaces line n of the current edit screen with blanks* Marks the screen
as updated*
COPY nl ri2 — FORTH
Copies the contents of screen nl to screen n2 on the disk*
CL nl n2 — EDITOR
"Copy line*" Copies lire nl of screen n2 to the pad* The current edit screen number does
not change*
DL n —
"Delete line*" Deletes line n from the current edit screen, Moving the lines below the
deleted line up* Saves the deleted line in the pad and marks the screen as updated*
DOn — EDITOR
Causes the top 16 lines of the display screen to be copied to the screen buffer* If
TOPFLAG contains $0, the display is copied to the 'upper' half (first 512 characters) of
the buffer? if TOPFLAG contains $200, the display is copied to the 'lower' half (last 512
characters) of the buffer • The buffer is then marked as updated, the screen is cleared,
and the top 16 lines are reprinted*
11*^ The Fig Editor * P*3
r. — FORTH
Sets up editing of screen n by establishing EDITOR as the CONTEXT vocabulary and setting
SCR (the current editing screen) to n.
— FORTH
Makes EDITOR the CONTEXT vocabulary* It will then be searched first when the input stream
is interpreted* The EDITOR vocabulary contains screen- and line-editing functions*
— EDITOR
The EDITOR version of FLUSH resets the screen Margins to (left) 2 and (right) 38,
establishes FORTH as the CONTEXT vocabulary, and Moves updated blocks fro* buffer to disk*
n — EDITOR
"Hold line*" Copies line n of the current edit screen to the pad*
n — EDITOR
"Insert line*" Inserts the lire in the pad after line r» of the current edit screen*
pushing the lines below it down (arid losing the last line of the screen)* Harks the
screen as updated*
— FORTH
Lists the current editing screen (screen number is obtained fron S£Rh
n — addr FORTH
Returns the starting address in disk buffer of line * n of the screen currently being
edited* If the line is not on the screen (ri>32) # an error Message is printed*
n — FORTH
Lists the contents of screen n with the Margins set to (left) 2 and (right) 38* The
nunber of each line is printed at the beginning of that line*
— EDITOR
Clears the display screen and displays the lower half of the current edit screen on the
top 16 lines* The word DOIT is printed two lines below the half-screen for the user's
convenience*
— FORTH
Lists the contents of the next screen
contents of SCR by D*
(screen nunber is obtained by increwenting the
n — EDITOR
"Replace line*" Replaces line n of the current edit screen with the lire in the pad*
Marks the screen as updated*
nl rtZ — FORTH
Lists the contents of screens nl to rt2, inclusive!
n — EDITOR
"Spread line*" Creates a blank line n on the current edit screen by pushing all of the
lines below it down* The last line of the screen is lost* Harks the screen as updated*
— FORTH
Hoves the next line in the input streaM to the pad; the line will end with a series of
blanks*
♦ ^ The Figt Editor, p ♦ ^
TOPFLAG
UL
n — EDITOR
"Type line*" Copies line n of the current edit screen to the pad, then types the line
with the line nunber arid the word $ preceding it. The line number and $ are there to
facilitate changes to the line*
— addr EDITOR
A variable used by the editor to keep track of which half of a screen is being edited*
Contains $0 if it's the 'upper' half (first 16 lines) or $200 if it's the 'lower' half
(last 16 lines)*
— EDITOR
Clears the display screen arid displays the upper half of the current edit screen on the
top 16 lines* The word DOIT is printed two lines below the half-screen for the user's
convenience*
ULL
n — EDITOR
Clears the display screen and displays one half of the current edit screen on the top 16
lines* The screen offset* n, determines which half is displayed ($0 for the 'upper' half,
$200 for the 'lower' half)* The screen margins are set to (left) 3 and (right) 34 • The
word DOIT is printed two lines below the half -screen for the user's convenience*
rtf n2 — FORTH
After compilation of FORTH code stops due to an error, the block * n2 and an offset nl
from the start of the block to the point where the error was detected are left on the
stack* Subsequent execution of Hf€RE will print the block * and the line on which the
error was found; EDITOR is then established as the CONTEXT vocabulary and SCR is set to
the block *♦
(
XX* 5 The Assewbler t P ♦ 1
The Atari computer contains a 6502 Microprocessor arid FORTH provides easy access to its assembly
language. This section does not explain assembly language programing in general or the 6502
instruction set in specific. There are good books available on the subject which should be consulted
first. This is intended to explain assembly language programming in FORTH, with a general discussion
of the instructions specific to the FORTH assembler and how they are used.
Syntactical differences : Like the rest of FORTH, the assembler uses reverse polish notation. In
standard assembly language programming the syntax ist
Cop-code mnemonic] [addressing model [operand]
e.g. LDA tO or STA (addr), Y ♦ With the FORTH assembler these appear in the order
[operand] [addressing mode] [op-code]
e.g. 0 *LDA, or addr )Y STA. Naturally, to accomodate this change there are certain
particular ways of writing the address modes that are not found in standard 6502. These are:
.A -accumulator mode t X -indexed with X
,Y -indexed with Y X) -indexed indirect with X )Y -ind. indir. with Y
The immediate mode is the same*. * ♦ Also, one need not write only one operation per line.
Op-code changes *. There are differences in the appearance of 6502 op-code mnemonics used by the FORTH
assembler} an alphabetic list of these differences appears below. Each op-code mnemonic has a
comma affixed to its end. E.g. ADC becomes ADC, . This sets off what would normally be one
line of assembly code arid helps to differentiate assembler words that might be interpreted as
hexadecimal numbers, such as ADC ♦ Also, V compiles into the dictionary, so the comma here
indicates the point at which code is generated.
Conditionals 4 . One thing missing from the FORTH assembler vocabulary is the set of standard branch
statements such as BCS or BEQ. Instead, this ASSEMBLER vocabulary is equipped with conditional
structures analogous to those in the FORTH vocabulary, including BEGIN , - UNTIL, loops and IF, -
ELSE, - ENDIF, . The comma serves to differentiate these words from those in the FORTH vocabulary.
With these conditionals comes a set of tests which specify branching by the conditionals which follow
them. For example,
CS IF, ELSE,
will generate a branch to the code following the IF, if the carry status bit is set, hut will
generate a branch to beyond the ELSE, if not. Other such tests include
0= 0< MS >=
NOT reverses the result of any test appearing 4 , for example, CS NOT IF, executes the code following
IF i if the carry status bit is not set. This method of branching eliminates the need for labels
within assembly code .
CODE and CI *♦ It is possible to write assembly code when not in the ASSEMBLER Vocabulary by using
the defining word CODE . CODE changes the CONTEXT vocabulary from CURRENT to ASSEMBLER making
available the assembler op-code mnemonics* At the end of a CODE definition the word CJ is used,
II ♦ 5 Tfre Assenbler * P * 2
returning CONTEXT to CURRENT ♦ CODE lets one name assenbler words as if they were in FORTH*
XSWE t The 6502 x register contains the FORTH parameter stack pointer ♦ When the x register is
being used in an assembly code definition for other purposes it Must be saved elsewhere and restored
before leaving ASSEMBLER* XSAUE leaves the address of a zero-page buffer for storing the x
register* It appears in assembly definitions in the forn XSAVE STX, and XSAVE LDX, ♦
NEXT and return of controls ! NEXT is a constant which returns the address of the FORTH address
interpreter, a subroutine that Moves execution frott one definition to the next. At the end of a
CODE definition control Must be returned to NEXT (i»e«i NEXT JHP,) or to another routine which
returns to NEXT such as POP , PQPTHQ f PUSH , and PUT (see the glossary for details on these words).
The glossary that follows contains the instructions used by the Atari FORTH assenbler « The
vocabulary in which a word is found appears at its right. Any effects on the stack, either at
assembly or run-tine are also given along with More detailed definitions and explanations.
6502 op-code MneMonics as ewployed by the FORTH assenbler J
one Mode pp-codes. Multi-Mode op-codes 4 .
BRKi
CLC,
CLD,
CLI,
CLV,
ADC,
AND,
ASL,
err,
CMP,
DEX,
DEY,
INX,
INY,
NOP,
CPX,
CPY,
DEC,
EOR,
BC,
PHA,
PHP,
Ft A,
PLP,
RTI,
JHP,
JSR,
LDA,
LDX,
LDY,
RTS,
SEC,
SED,
SEI,
TAX,
LSR,
Fa,
ROR,
SEC,
TAY,
TSX,
TXS,
TXA,
TYA,
STA,
STX,
STY,
t — ASSEMBLER
Specifies iMMediate addressing Mode for the next op-code generated.
)Y — ASSEMBLER
Specifies indirect indexed with Y addressing Mode for the next op-code generated.
,X — ASSEMBLER
Specifies indexed with X addressing Mode for the next op-code generated.
■
,Y — ASSEMBLER
Specifies indexed with Y addressing node for the next op-code generated.
,A — ASSEMBLER
Specifies accumulator addressing node for the next op-code generated,
0< — cc (assembling) ASSEMBLER
Specifies that the following conditional generate a branch if the previous operation has
produced a negative result, i.e., the sign bit of the status register is set (s=l). The
flag cc is left at assembly %im\ there is no run tine effect on the stack.
II ♦S The Assembler , P * 3
0= — zz (assembling) ASSEMEtER
Specifies that the following conditional generate a branch if the previous operation has
produced a zero result, i*e*, if the zero-bit of the status register is set (z=D* The
flag zi is left at assembly tine, there is no run-time effect on the stack*
>= — cc (assembling) ASSEMBLER
Specifies that the following conditional generate a branch if the zero bit of the status
register is set (z=l), or if the sign bit is positive (s=0)* It is only correct after
SUE:, or CMP* ♦
ASSEMBLER — FORTH
Makes ASSEMBLER the CONTEXT vocabulary* It will then be searched first when the input
stream is interpreted*
BEGIN, — addrl (assembling) ASSEMBLER
— (run-time)
A word in CODE definitions used to nark the start of a loop* Used in the form**
BEGIN, *♦* cc UNTIL,
At run-time, it narks the return point for the corresponding UNTIL,* When reaching
UNTIL,, abranch ack to BEGIN, will occur if the status bit cc left by the conditional
prior to the UNTIL,, is false*, otherwise execution continues ahead* At assembly tine,
BEGIN, leaves the dictionary pointer address addr and the value 1 for later testing of
conditional pairing by UNTIL,*
BOT — n ASSEMBLER
Used in code assembly in the form**
BOT LDA, or BOT 1+ X) STA,
It addresses the bottom of the parameter stack by selecting the indirect x node and
leaving n=C at assembly time* n nay be modified to another byte offset into the parameter
stack* It must be followed by a nulti-node op-code nnemonic*
CODE — FORTH
Defining word used in the form*
CODE cccc ♦*♦ CJ
Creates a dictionary entry for cccc in the CURRENT vocabulary*, the CFA of cccc contains
the address of its parameter field, The CONTEXT vocabulary is set to ASSEMEtER, to make
the assembler mnemonics available* Hhen cccc is later executed the machine code in this
paraneter field will execute*
CPU ri — (compiling assembler) ASSEMBLER
An assembler defining word used to create assembler mnemonics that have only ore
addressing mode* For example** 88 CPU DEY, creates the word DEY, with its op-code 88 as a
parameter* Hhen DEY, executes it assembles 88 as a one byte op-code*
XX* 5 The Assembler, P ♦
— cc (assembling) ASSElfLER
Specifies that the following conditional generate a branch if the carry hit of the status
register is set (c=0)* The flag cc is left at assembly time? there is no rut-tine effect
on the stack*
— (run-time) ASSEMBLER
addrl 2 — addr2 2 (assembling)
Occurs within a code definition in the form*
cc IF, (true) ELSE, (false) ENDIF,
At run-time ELSE, sets off a section of code that will be executed if the condition
specified by cc is false* At assembly-time ELSE, assembles a forward jump to just after
ENDF, and resolves a pending forward branch from IF, ♦ The twos are used for error
checking of paired conditionals*
— ASSEMBLER
A compiling version of UNTIL,*
— (run-tine) ASSEMBLER
addr2 — (assembly-time)
Occurs in a code definition in the form*
cc IF, (true) ELSE, (false) ENDIF,
At run-tine ENDIF, marks the conclusion of a conditional structure* Execution of either
the true or false part. continues after ENDIF,* Hhen assembling addr and 2 are used to
resolve the pending forward branch to ENDIF,*
cc — addr 2 (assembly-time) ASSEMBLER
— addr 2 (run-time)
Occurs within a code definition in the form*
cc IF, (true) ELSE, (false) ENDIF,
At run-time IF, branches based on the condition code cc* If the status bit specified by
cc is true execution continues ahead* If false a branch is generated to the next ELSE,
(if present) or to the following ENDIF,*
Hhen assembling IF, creates a forward branch to an undetermined location based on the
condition code cc, and leaves addr and 2 for resolution of the branch by the corresponding
ELSE, or ENDIF,* Conditionals may be nested*
— addr (assembling) ASSEMBLER
An array used within the assembler, which holds bit patterns of allowable addressing
modes* (Do not confuse with INDEX in FORTH vocabulary*)
— addr ASSEMBLER
A constant that returns the zero-page address of the Interpreter pointer, specifying the
next FORTH address which will be interpreted by NEXT* It is used in code definitions in
the form**
TP STA, or IP )X LDA,
nit n2 — (compiling assembler) ASSB&LER
An assembler defining word used to create assembler mnemonics that have multiple
addressing modes. For example! 1C6E 60 M/CPU ADC, creates the word ADC, with two
parameters, When ADC, executes it uses these parameters, the stack values, and the
contents of HODE to calculate arid assemble the correct op-code arid operand,
— ASSEffcLER
Used within the assembler to set HODE to the default value for direct memory addressing,
zer o-page*
— addr ASSEHBLER
A variable used within the assembler, which holds a flag indicating the addressing mode of
the op-code being generated ♦
— ASSEMBLER
A constant address of an 8 byte utility area in zero-page, See SETUP*
— addr (assembling) ASSEHBLER
This is the inner interpreter that uses the interpretive pointer IF' to execute compiled
FORTH definitions. It is not directly executed but is the return point for all code
procedures, It acts by fetching the address pointed by IP, storing this value in register
Hi It then jumps to the address pointed to by the address pointed to by H, H points to
the code field of a definition, which contains the address of the code which executes for
that definition, This usage of indirect threaded code is a major contributor to the
power, portability, arid extensibility of FORTH,
ccl — cc2 ASSEMBLER
Used in ASSEHBLER conditionals, it reverses the condition code for the conditional that
follows, For example*, CS NOT UNTIL, will terminate the loop if the carry is not set,
— addr (assembling) ASSEMBLER
n — run-time
A constant which leaves (during assembly) the machine address of a routine which at
run-tine will pop a 16-bit value from the computation stack arid return control to NEXT,
— addr (assembling) ASSEMBLER
nl, n2 — (run-time)
A constant which leaves (during assembly) the machine address of a routine which at
run-time will pop two 16-bit values from the computation stack arid return control to ICXT
XI ♦ 5 The Assertb ler
PUSH — 3ddr (assembling) ASSEMBLER
— n (run-time)
A constant which leaves (during assembly) the Machine address of a routine which at
run-time will add the accumulator (as high byte) and the bottom of the machine stack (as
low byte) to the computation stack* It returns control to NEXT*
PUT — addr (assembling) ASSEMBLER
nl — ri2 (rurrtime)
A constant which leaves (during assembly) the machine address of a routine which at
run-tine will write the accumulator (as high byte) and the bottom machine stack byte (as
low byte) over the existing top of the computation stack (16-bit value nlh
Rp) — n (assembly-time) ASSEMBLER
Used in code definitions in the form:
RP) LDA* or RP) 3 + STA*
Addresses the bottom* low order byte of the return stack by selecting the *X mode and
leaving n=$101 or maybe modified to another byte offset* Before operating on the return
stack the x register must be saved in XSAVE and TS<* executed* and the x register mist be
restored before returning to NEXT*
SEC — n ASSEMBLER
Identical to EOT except that n=2* Addresses the low byte of the second 16-bit parameter
stack value, the third byte on the parameter stack*
SETUP — ASSEMBLER
A subroutine which moves stack values to the N area* In this subroutine the accumulator
specifies the quantity of 16-bit stack values to be moved (1-4) ♦ For example 4 *
3 *LDA* SETUP JSR*
takes the first three pairs of bytes from the stack and moves them to N*
Stack before N after Stack after
H H high byte
G BOT G low byte
F F
E E
D D
C C
B high byte B
EOT A low byte A
THEN, — ASSEMBLER
A caviling version of ENOIF,.
UNTIL,
— (run-tine) ASSEMBLER
addr, 1, cc — .(assembling)
A word in CODE definitions that is the terminator of loops, used in the form:
BEGIN, ♦ ** cc UNTIL,
At rurrtime UNTIL, controls the conditional branching back to BEGIN, ♦ If the specific
status bit specified by cc is false execution returns to BEGIN,, if true it continues
ahead*
At assembly time UNTIL, assembles a conditional relative branch to addr based on the
condition code cc* The number 1 is used for error checking.
UP
— addr (assembling) ASSEMBLER
A constant that returns the address of the pointer to the base of the user area* It is
used in CODE definitions in the form*
UP LDA, or UP )Y STA, ,
UPMODE
addr f — addr f ) ASSEMBLER
Used within the assembler to adjust the addressing mode based on operand size and op-code
type*
MS
— cc ASSEMBLER
Specifies that the following conditional generate a branch if the overflow bit of the
status register is set*
— addr (assembling) ASSEMBLER
A constant that returns the address of the pointer to the code field (execution address)
of the FORTH dictionary word being executed* It is used in CODE definitions in the form:
W 1+ STA, or H 1- JMP, or H )Y ADC,
Indexing relative to M can yield any byte in the definition's parameter field. For
example 2 * LDY, H )Y LDA, loads the first byte of the parameter into the accumulator*
X)
— ASSEMBLER
Specifies indirect indexed with x addressing mode for the next op-code generated*
XSAVE
— addr (assembling) ASSEMBLER
Used in code definitions in the form!
XSAVE STX, or XSAVE LDX,
A constant which leaves the address of a temporary buffer for saving the x register at
assembly time* Since the x register indexes to the data stack in zero-page, it must be
saved and restored when used for other purposes*
iii + i wtobj: write bootable object
HTOBJ is a way to create bootable object disks* When the screens containing the HTOBJ words are
loaded* the FENCE is reset to the top of the dictionary as it was just before the screens were
loaded. Short instructions for using FORHAT and HTOBJ are printed out* To create an object code
boot disk* you should FORHAT it (if it isn't formatted already) * then put the disk, in drive *1 and
type HTOBJ ♦ HTOBJ will write a short machine code routine (pointed to by BOOT) onto sector 1,
followed (on succeeding sectors) by the contents of the dictionary up to FENCE* When this new disk
is booted, the routine on the first sector will load in the rest of the boot* This version of HTOBJ
will only create boot disks of 255 sectors or less*
CALLDK
Routine for Moving a sector to or from disk.* Assumes that the device control block has
been set up*
DKIO
addr nl nZ —
Instructs the disk, drive specified by the lower byte of n2 to perform a disk operation on
sector nl* The upper byte of n2 determines which operation (read, write, format, etc*) is
performed* addr is the address of the 128 byte buffer used for this operation*
HTSEC
addr n —
Hrites 128 bytes, starting at addr, to sector n of drive *1*
RDSEC
addr n —
Reads 128 bytes from sector n of drive tl to memory, starting at addr*
FORMAT
n
Formats the disk in drive n* First asks whether the user really wants to format, just in
case*
BOOT
— addr
Points to the starting address in memory of the code routine that is put onto the first
sector of a bootable object code disk (by HTOBJ) ♦ Hhen this disk is booted later, this
routine loads in the rest of the object code that was put onto the disk by HTOBJ*
HTOBJ
Creates a bootable object disk out of the FORMATted disk in drive *1« First puts the code
routine that BOOT points to onto sector 1, then writes the contents of the dictionary (up
to FENCE) to the disk* FENCE was reset to the top of the dictionary when the HTOBJ
screens were loaded. Hhen this new disk, is booted, the code in the first sector will load
in the rest of the boot*
Coin-Op FORTH provides a set of disk copying routines in source code which can he loaded on top
of the boot i The nost important of these are CLONE » OBJ i and COPYDISK • For each of these, the
source disk should he inserted in drive 1, and the destination disk in drive h More of then has any
effect on the stack* Executing CLONE will copy the entire source disk.* OBJ copies only the original
Coin-Op boot screens (probably screens $ - B to -1, unless PHYSOFF or OFFSET have been changed by the
user)* If extra boot screens are added OBJ will not copy them* COPYDISK will copy the entire disk
except for the Coin-Op FORTH boot screens*
111*3 Line Printer WoircJ -ee>
CoirrOp FORTH provides a set of words for printing disk screens on the line printer • Although
written for use with the Atari 822 printer, one snail Modification will Make then suitable for use on
an Atari 825 or an equivalent printer (such as the Centronics 739) ■ This Modification is as follows!
on the second line of the first screen of source code for the printer words, the definition
3A50 VARIABLE P!
should be changed to
3250 VARIABLE Pi 3A ,
This places the ATASCII characters P2t , rather than P! , into the parameter field of this variable*
This change only needs to be Made if you are not using an Atari 822 printer*
The printer should be turned on (as should any interface Module used to connect the printer to
the Atari) and switched to ON-LINE when the printing words are loaded, or else the printer will not
be "opened". The comand LPOPEN will open the printer after a SYSTEM RESET (or if the printer was
not on line when the printing words were loaded)*
There are three basic line printer routines available to the user* The first is LISTLP* which
simply takes a disk screen number off the stack and prints that screen on the line printer* SHOWLP
takes two arguments, a final screen it, and a starting screen n, and prints screens n to m on the line
printer* If the number of characters per line on a screen is equal to 32, the screens will be
printed in two columns? otherwise the screens will be printed in ore column* Finally, LPINDEX takes
the same arguments as SHOWLP, but prints only the first line of each screen*
The Atari words also allow the use of two different styles of print* After SHRBK is executed,
files will be printed in condensed print* EXPAND returns the print size to normal*
♦CLP n —
Takes a number n from the stack and prints it at the line printer* If r» is a single-digit
number, it will print a preceding 0*
•LP n —
Takes a number n from the stack and prints it on the line printer*
CF1P
CRLP checks LPCNT, and if the bottom of the page has been reached (if the number in LPCNT
is greater than $30) performs four carriage returns on the line printer to get to the next
page*
EXPAND
After EXPAND is executed, files printed on the line printer will be printed with normal
width characters*
(Form feed*) FFLP performs successive carriage returns on the line printer until the top
LISTLP
III ♦ 3 Line Pr i nter Wor ds, p ♦
of the next page has been reached
UMELP n —
FT i nts line n of the host recently referenced disk screen on the line printer*
n
Prints screen n with line numbers on the line printer*
LPCNT
— addr
A variable which holds the number of carriage returns the printer has performed on a page*
LPCR
Performs a carriage return on the line printer and increments LPCNT
LPEMIT
n —
Takes one ATASCII character from the stack and prints it on the line printer*
LPINDEX n, m —
Prints line 0 of screens n through m on the line printer*
LPOPEN
OPENs a line printer device/file* This must be called before using any printer words*
LPSPC
n —
Prints n spaces on the line printer*
LYP1
addr* m —
Sets the beginning of the line printer I/O buffer to addr with length n bytes, and prints
the contents of the buffer •
LYPE
addr* n —
Prints m bytes of the buffer starting at addr on the line printer, followed by a
If the buffer is longer than one line (80 characters) it increments LPCNT*
pi
— addr
A variable which contains the ATASCII equivalent of the characters Pi, if an Atari 822
printer is being used, or P25 if an Atari 825 or equivalent printer is being used*
PI is used as a buffer in opening the printer device/file.
- n
Used after parameters are set for line printer I/O* PCIO sets up
CIO entry point ($E456h The I/O status is left on the stack*
> #7 and jumps to the
Ill* 3 Line Printer Words^ p*3
PERR?
n
Takes the I/O status n fro* the stack and checks for error* If an error is found, PERR?
executes ERROR*
SCR*
— addr
A variable which holds the ATASCII equivalent of the characters SCR **
SHOHLP n f m —
Prints screens n through n on the line printer* If the number of characters per line on
the screens is equal to 32, the screens will he printed in two columns on the page*
Otherwise the screens are printed in ore column*
SHRINK
After SHRINK is exerted, files printed on the line printer will he printed in condensed
print*
XXX «4
These words are useful when you have to decipher compressed FORTH source code (you should rarely
have to write such code yourself, since disk, space is not expensive)* The words allow you to list or
print screens in a formatted fashion - they cone out looking the way they should have in the first
The line printer words Must be loaded before the formatted print words*
The wain words are**
FLST a fornatted equivalent of LIST
FLSTLP LISTLP
FSHW SHOW
FSHWLF — _ — — — SHOKlP
Each first lists or prints the screen in normal fashion, then in formatted form,
FSHHLP « n —
For screens n through n, first prints then prints a formatted version*
FSHW m n —
For screens m through n, first lists, then lists a formatted version on the TV screen.
FLSTLP
FLST
n
Lists screen n on the printer, then prints the formatted version of the screen*
n
Lists screen n on TV screen* then lists formatted version*
1 Miscellaneous, Glossary * p*1
Causes the next word in the input stream to be interpreted as a hexadecimal number . At
compile-time, the number is compiled into the next available dictionary space} at
run-time, the number is left on the stack*
Causes the next word in the input stream to be interpreted as a decimal number • At
compile-time, the number is compiled into the next available dictionary space; at
run-time, the number is left on the stack*
2DR0P n m —
Drops the two top elements of the stack*
2DUP ri m — n m n m
Duplicates the top two elements of the stack*
ftTftSCII>IHTEim B — i
Code routine which takes the ATASCII value of a given character and returns the
corresponding Internal value*
COLCRS — addr
A constant which returns the address that controls the full text screen text cursor's
horizontal position (the split screen text cursor's horizontal position is controlled by
TXTCOD*
INTERHAL>ATASCn i — a
Takes the Internal value of a character and converts it to the ATASCII value*
HAP — addr
Returns the address of the first entry in a table used in the conversion of characters
from ATASCII to Internal representation, and vice versa*
MOVE addrl addr 2 n —
A "smart" form of CM0VE which moves bytes without danger of incorrect overwriting* Takes
n bytes starting at addrl and moves them to the n bytes starting at addr2* Written in
machine code*
PICK xn ♦ . ♦ x3 x2 xl n — xn xl x2 x3 * * . xn
Takes the nth value from the stack, duplicates it, and puts it on top of the stack (a
generalized form of OVER)*
ROLL xn * * * x3 x2 xl n — xn xl x2 x3 * * *
Pulls out the nth value on the stack, xn, and puts it on top of the stack* The values
which were above xn are pushed down one position to fill its place (a generalized ROT)*
RCBCRS — addr
A constant which returns the address that controls the full text screen text cursor's
vertical position (the split screen text cursor's vertical position is controlled by
I) i
IU* 1 Miscellaneous, Glossary, P *2
SWMSC
— addr
A constant which contains the starting address of the graphics screen data.
SETBV
— addr
A constant which returns the address of the vector into the OS routine SETVBV} this
used to set titters and all new routines to VBLfiNK. See the OS Manual for details*
is
TXTCOL
— addr
A constant which returns the address that controls the split screen text cursor's
horizontal position*
TXTOSC
TXTROW
WBLKD
WELKI
— addr
A constant which
contains the address of the beginning of the text screen data,
— addr
A constant which returns the address that controls the split screen text cursor's vertical
position*
— addr
A constant which returns the address of the deferred vertical blank vector*
-
— addr
A constant which returns the address of the iwediate vertical blank vector*
Use this exactly the same 35 regular INDEX* It is Much faster since it looks at only the sector
Containing the top line of a screen, rather than reading in the whole screen* We have it compiled
into our noma! boot*
This word requires $ from the Miscellaneous Words*
Programed by Charles A* Clinton
INDEX m n —
Writes the top lines of screens k to n on the TV screen*
Supporting words on the source screen!
DISKIO , INDE<_0NE_SECT0R , INDEX.ONE.SCREEN
The CASE structure is a powerful branching system which offers an easy-to-use and
maintain alternative to nested IF.*.THENs* The basic CASE structure is as follows
n CASE
ml OF xxxl FO
«2 OF >oo«2 FO
♦
♦
♦
my OF xxxy FO
OTHERWISE OF mo FO
ESAC
At execution, the entry value n is compared with ml, m2, ♦♦* my* If n is equal to some mi, the
string of words mi is executed, and execution exits the CASE structure* If n is not equal to any
of nli tfZj *♦« mil the OTHERWISE conditio, xxxO, will be executed, and execution will leave the
structure (if no OTHERWISE condition is included, ESAC will clean up the stacks, and execution
continue to the next word in the definition). An important thing to note is that ml, m2, ♦ ♦♦ ny can
be either literals or set of words, provided they leave a number on the stack to be compared with n
by OF.
EXAMPLE**
Suppose you need a program called MSHS that will keep track of the number of different colored
n&ns in a bag as you eat then *e*g*
3 brown mm
will increment the variable BROWN by 3* This can be done using CASE as follows:
0 VARIABLE BROWN
0 VARIABLE YELLOW
0 VARIAEtE ORANGE
0 VARIABLE GREEN
mm (n, addr —
BROWN OF BROWN +! FO
YELLOW OF YELLOW + ! FO
ORANGE OF ORANGE + ! FO
GREEN OF GREEN +! FO
ESAC :
)
CASE
When, for example, the line*
2 GREEN HSHS
is executed, the number 2 and the address of the variable GREEN are left on the stack* This address
is first compared with the address of the variable BROWN, then that of YELLOW and ORANGE, and finally
GREEN* Since the address of GREEN left on the stack outside the CASE structure will equal the
address of GREEN left on the stack inside the CASE structure, the string GREEN +! will be executed,
of GREEN will be incremented by two*
This can be a very useful program, since it is important not to eat too many green m&ms (they
make you sterile).
XV* 3 Case, P *2
$CASE
$F0
Run-tine procedure conpiled by CASE which places the following in-line paraneter on the
return stack* This parameter is the address later used by $F0 to exit fron the CASE
structure*
The run-tine procedure compiled by FO which causes execution to exit fro* the CASE
structure i
$0F n n — (if n%)i or
n n — n (if n On)
The run-tine procedure compiled by OF* This compares two values on the stack, and if they
are equal, executes the words following $0F* Otherwise it leaves n on the stack and
execution continues after the next $F0.
CASE run- tine 4 * —
conpile-tine* — addr
Used in the forn*
n CASE
ml OF xxxl FO
h2 OF xxx2 FO
ny OF xxxy FO
OTHERWISE OF xxxo FO
ESAC
CASE opens the CASE branching structure which compares n to ni, h2 t etc* If n is equal to
ni, then the string of words xxxi will be executed and FO will cause execution to exit the
CASE structure Any t\i nay be a literal or a string of words which leave a value on the
stack to be conpared with n* If none of nl,*** ny are equal to n, the OTHERWISE string,
xxxo, will be executed* Then execution continues after ESAC*
At conpile-tine, CASE compiles the run-tine word $CASE, and reserves space at addr for use
by ESAC*
ESAC run-tine* n —
conpile-tine J addr —
Used at the end of a CASE structure. At run-tine, ESAC cleans up the return arid paraneter
stacks if no natch for the entry argunent was nade inside the CASE structure (if a natch
. was nade, FO would have caused execution to exit the structure, and ESAC would not be
executed),
At conpile-tine, ESAC conpiles R> and 2 DROPS to clean up the stacks, and stores the next
available dictionary position into addr, which was left on the stack by CASE*
IU ♦ 3 Case , p ♦ 3
FO
run-tine** —
conpile-tine** addr —
At run-tine, FO causes execution to exit fron the CASE structure if a watch for the entry
argument has been nade* (See CASE*)
At conpile-tine, FO compiles the run-tine word *F0 and stores the address of the next
available dictionary position into addr, which was left on the stack by OF*
OF
run-tine* n rt — (if n=n)
ori n n — n (if nOn)
conpile-tine** — addr
At run-tine, OF compares two values on the stack (n was left on the stack before the CASE
structure was entered; ft was left on the stack inside the CASE structure)* If these
values are equal, the string of words* xxx will be executed* and the following FO will
send execution out of the CASE structure* If the values are not equal, OF leaves h on the
stack-., and execution continues after the following F0*(See CASE*)
At conpile-tine, OF compiles the run-tine word $0F, and reserves space at addr for use by
FO*
OTHERWISE
n — n n
Used in the CASE structure in the forn**
OTHERWISE OF xxx FO
OTHERWISE will cause the string of words xxx to be executed* OF is expecting to conpare
two values on the stack and execute xxx if they are equal*, OTHERWISE sinply duplicates the
value on the stack*
IV + 4 LIST ASSEMBLER WORDS
These words allow the user to create ANTIC display lists in the FORTH dictionary* Read De Re
ATARI chapter 2 (ANTIC and the Display List) before using these words*
These words have four advantages* First, because they employ Mnemonics, creation and
Maintenance of display lists becomes Much easier than would be the case if the user had to deal
directly with the numerical ANTIC cowhands* This is roughly analogous to the difference between
writing Machine code via an assembler and writing it "by hand" - number by nuMber* (Of course * in
the case of both Machine code and display lists, the user should have at least soMe understanding of
the underlying nuMerical coMMands*)
The second advantage lies in the convenience of placing display lists in the FORTH dictionary,
where they are created at conpile tine and can be easily accessed* This saves the user froM the
hassles of Moving custoM-huilt display lists in fro* disk or building then at run-tine t and it avoids
the probleMS of finding space for a display list between player/Missile MeMory and display MeMory*
The words are quite easy to use* Bear in Mind that, like FORTH assembler Mnemonics, they
operate in execution rather than cohpile Mode* (This Means that they can be placed inside other
FORTH words to create "Macros"*)
A dictionary based display list starts with the coMMand J DUST , followed by the user's nane for
that diplay list" (let us use the nane DL*EX)* iDUST will create a FORTH header for DL*EX*
Subsequent execution of DL*EX will leave its PFA on the stack 1 , this in turn is the first byte of the
new display list*
After the header, the diplay list is created* This is done through the use of the following
four coMMands* (All of these coMMands have a , (coMMa) as the last character of their nane? this
indicates that they store a value onto the dictionary*)
JMP, - This coMMand causes display list execution to ".Jump" to a new address (other than the
next byte in MeMory), where the display list will continue* It has the effect of leaving one blank
scan line on the display screen, and it is rarely used* JHP, is used in the for-M*
addr JHP,
where addr is the address to which the display list will Jump*
BLANK , - This is used in the forM?
n BLANK,
This coMMand places between 1 and 7 blank scan lines on the screen* n indicates how Many blank lines
are desired* It is always used at the beginning of display lists (see De Re Atari), but it car. be
used anywhere the user desires*
MODE, - This is used to set up graphics Mode lines* It is used in the forM*
[address (of LMSV3 [options] [Mode #3 HODE,
This creates an ANTIC instruction indicating one Mode line of graphics Mode [Modetl* It May also
indicate one or More of these four options - LHS (load MeMory scan), VSCROLL (vertical scrolling
enabled), HSCROLL (horizontal scrolling enabled), or DLI (display list interrupt)* The option or
options should be indicated before the Mode line *♦ Finally, if one of the options is an LHS, the
word LHS should be preceeded by the LHS address (i*e*, the address of the start of display da J *
XV *^ Display List, Assembler * p ♦ 2
For example j
$ BOOO LMS VSCROLL 2 MODE,
will create en ANTIC Mode 2 (graphics 0) Mode line, with vertical scrolling enabled and an LMS which
indicates display MeMory starts at i B000» Another exanplet
6 MODE,
creates an ANTIC Mode 6 (graphics 1) line*
The word OF-THEM is used to indicate that not one but several node lines identical to the one
Most recently created should be placed in the display list* Thus, the connandt
VSCROLL 7 MODE, 10 OF-THEM,
will coMpile 10 Mode 7 (graphics Mode 2) lines with vertical scrolling enabled 4 , this avoids the
necessity of repeating coMplicated (or even uncoMplicated) instructions a nuMher of tines* OF-THEM,
can also be used with BLANK,*
JVB, ♦ This is used in the forM**
Caddrl JVB,
arid indicates that the screen is conpleted, and as such display list execution should Jump to Caddrl
and wait for vertical blank to occur* CaddrD will alMost always be the address of the first byte of
the display list; this address can be obtained by executing the nane of the display list!
DL*EX JVB,
will thus cause display list execution to Jump to the top of display list DL*EX*
A dictionary-based display list ends with the FORTH word DL*, * This word checks to see if the
display list crosses a IK boundary (which is not allowed)* If it does, a Message to this effect is
issued to the user, who Must then either rearrange the source code or allot eMpty space in the
dictionary so that the display list does not cross the boundary*
NOTE** There is one real disadvanege (other than the boundary probleM just Mentioned) with
dictionary based display lists* Because they are created at coMpile tine and used directly, it can
be very difficult to "clean up" a display list after it has been altered in soMe way (for exaMple,
scrolling will change the LMS addresses)* It May be necessary to store LMS addresses and the like in
separate constants and to have a word which uses these constants to recreate the "original" display
list*
After the display list is created, execution of its nane will return its starting address* This
address can then be stored into S-DUSTL ($230) in order to activate the display list.
Here are 2 exaMples of display lists (in deciMal fori*)*
JDLIST DL*EX1
7 BLANK,
3 OF-THEM
$ BC60 LMS 2 MODE,
2 MODE, 23 OF-THEM,
DL.EX.l JVB,
DLJ
(This creates a normal graphics Mode 0 screen of 24 lines, the first of which has an LMS*)
XV + *\ Di«&pl3'bf List Assenbler * p ♦ 3
!DUST DL*EX2
7 BLANK, 3 OF-THEH,
$ BOOO LMS VSCRDLL 7 MODE,
VSCROLL 7 MODE, 9 OF-THEH,
DLI 7 MODE,
$ Ef60 LHS 2 MODE,
2 MODE, 3 OF-THEM ,
DL*EX2 JVBi
DL?
(This creates 3 10-line scrolling graphics hode 2 screen with 3 four line graphics mode 0 text
window! there is a DLI just efore the text window* See Se Re Atari chapter 6 for an explanation of
why there are 11, rather than 10, ANTIC node 7 instructions*)
The Display List Assembler words were programmed by Charles A* Clinton*
♦DUST
Used in the form*
J DUST xxxx Mt-DL!
4 *DLIST creates a dictionary entry for xxxx and sets MASK to 0, thus setting up the
conditions for compiling a display list into the dictionary* ANTIC instructions can then
be stored into xxxx's parameter field by using the display list assembler instructions*,
compilation of the display list is terminated by DL*,* When xxxx is executed, it leaves
its PFA on the stack*, this is the address of the first byte of the display list, which can
then be used to instruct ANTIC to use display list xxxx* At compile-time J DUST leaves
addr (xxxx's PFA) on the stack, for subsequent error checking by DL}*
BLANK,
n
Compiles an ANTIC instruction in the dictionary* The instruction calls for n blank scan
lines, where n - 1 ■• -to 7*
dl;
addr —
Finishes compiling a display list by ensuring that the display list has not crossed a IK
boundary; if it has, a message to this effect is issued to the terminal, and
interpretation of the input stream continues normally* addr is the address of the first
ANTIC instruction in the display list, which is left on the stack by JOUST*
DU
Adds $80 to the display list instruction currently being created (contained in MASK)*
This indicates that a display list interrupt will occur on the mode line corresponding to
the instruction*
BSCROLL
Adds $10 to the ANTIC instruction currently being created* This indicates that horizontal
scrolling is enabled on the mode line corresponding to the instruction*
XM*^ Display List Assembler * P ♦ ^
addr —
Compiles an ANTIC JHP instruction, along with the address with which to reload the display
list counter, into the dictionary. This instruction will leave one blank, scan line on the
screen*
addr —
Compiles an ANTIC "Jump and wait for vertical blank to end" instruction, along with the
address with which to to reload the display counter* This address is usually the starting
address of the display list.
LHS
Adds $40 to the ANTIC instruction currently being created. This indicates that a "load
memory scan" should occur on the mode line corresponding to the instruction*
MASK
— addr
A variable used to hold display list instructions temporarily as they are being created.
MODE,
addr, n — (LHS)
n — (non-IMS)
Compiles an ANTIC instruction into the dictionary. The instruction indicates one node
line of ANTIC node n, along with any other conditions (LHS, vertical arid/or horizontal
scrolling, DLI) preset in MASK. If the mode line contains an LHS, the new display data
address is compiled immediately following the ANTIC instruction* MASK is reset to zero.
OF-THEMj
n
Follows BLANK* or MODE,. Compiles ml ANTIC instructions, identical to the last one
compiled before entry into OF-THEM, into the dictionary (e.g., 2 MODE, 23 0F-T}£M will
compile a total of 23 ANTIC mode 2 lines).
Sets MASK to 0, in preparation for the creation of the next ANTIC instruction.
VSCROLL
Adds $20 to the ANTIC instruction currently being created (contained in MASK). This
indicates that vertical scrolling will be enabled on the mode line corresponding to the
instruction*
The word on the source screen is actually a tenplate. To use just change the 8 x 8 natrix of O's
and 1's to for* the character desired arid renane the resulting word* Replace "beginning addr." by
the beginning address of your character set (see the discussion below) . To replace a character by
your character, find its Internal number n in the Internal Character Set (Table 9*6 of the Basic
Reference Manual) , and do n <your na*e for word>. For example 0 ARROH-HEAD would replace "space" by
the arrowhead ♦
This routine requires * fro* the Miscellaneous Words ♦
Character set manipulation}
The highest two hexadecimal digits of the address of the beginning of the character set
currently being used are stored in the variable CHBAS (normal value $EQ) , the other two digits of the
address are 00.
To change the normal character set, select a memory address beg.addr, which lies on a IK
boundary (i.e. its last 2 digits must be 00), arid for which you can afford to dedicate the following
1024 bytes to character set storage. Then CHQVE $400 bytes fro* $E000 to beg.addr. This gives you a
changeable character set ($E000 to *E4Q0 is in ROM). Change characters as described above. To make
your new character set the current one, take the highest two digits of beg .char and do CHBAS C!
After having modified a character set, you nay wish to store it on disk.
IV.6
To find all appearances of a string xxxx on screens scrl through scr2 inclusively* type:
scrl scr2 SEARCH xxxx
The computer will print out each line that contains the string, along with the line nurter and the
screen nuftber*
SEARCH will recognize leading, but not trailing blanks* Thus, letting T denote blank,
n r. SEARCHbFF
would picks up both "BUFFER" and "$ FF" but
ft n SEARObbFF
would only pick, up "$ FF M »
Supporting words on the source screens *♦
♦LOCATE, *LEAD, *LAG, INFORM, TOP MATCH, 1LINE, FDO, COUNTER, BUT.
Programed by Jay Scott ♦
(
IV*7 F=>3R.I2SIT COMMANDS FOR GRAPHICS
MODES
The graphics printing words work exactly like the normal FORTH text printing words, except that
they print characters in graphics Modes* For each of three graphics nodes (nodes 1, 2 and 7), there
are words that correspond to BUT* TYPE, arid , and words that position the cursor for printing*
There are also counterparts to EMIT, TYPE, and • " for the text window (the parameters that position
the cursor in the text window are given directly to T H ). Since graphics characters are represented
in nenory in INTERNAL rather than ATASCH forn, there are words that do what * , #S , HOLD , SIGN ,
and WORD do, except that they create a string in INTERNAL forn instead of AT ASCII* These words are
used to format pictured numeric output* TOJXTERNAL will convert a string fron ATASCIE to INTERNAL
representation. Other useful words in the graphics printing set include 7REMERSE, a variable which
deternines whether node 7 characters should he printed in nornal or inverse video forn; and
D_Etf;-TEXT4CDIMW, which clears a portion of the ted window*
Internally, the graphics printing words use SAUMSC and TXTHSC, which tell where the first bytes
of graphics arid text nenory are, respectively* The node 7 words use XPA!€&CQL0R, which tak.es an
8-bit slice of a character in the character set and widens it to 16 bits for printing in the higher
resolution node 7* (Mode 7 characters look, exactly like node 2 characters*)
These words require * fron the Miscellaneous Words*
The graphics printing words were programed by Chris Helck*
#-I dl — d2
Fron a double number dl, generates the next character (in Internal, not ATASCH,
representation) which is placed in the pictured-nuneric output strean* The double nunber
d2 is the quotient after dl is divided by BASE and is naintained for further processing*
(Direct conterpart to #♦) Use only between <* and *>*
*S-I dl — d2
Converts all digits of the double nunber dl to pictured nuneric representation, adding
each digit to the output text} the resulting text is in Internal, rather than AT ASCII,
representation* The double nunber d2 is the renaining quotient, arid is always zero*
(This is a direct counterpart to *S*) Use only between <* arid *>*
<1") —
Run tine code for 1" and 2'\ Prints the following in-line string (in Internal
representation), with a count in the first byte, on a node 1 or 2 screen* The string's
color will be deternined at run-tine, on the basis of what color was nost recently
selected by the user*
in —
Run-tine code for 7"* Prints the following in-line text string (in Internal
representation), with a count in the first byte, on a node 7 screen*, the string will be
printed in the color nost recently set*
(T")
r
IV* 7 Graphics Printing; Words, p*Z
nl n2 —
Execution procedure for T n * Prints the following in-line text string,
the first byte, in the text window starting 3t column nl, row n2*
in
Used in the form*
r xxxx"
Compiles an irrline string xxxx, delimited by M (double quotes), with an execution
procedure (1") to transmit the text to a mode 1 screen (in the color most recently set by
a COLOR command)* If executed outside of a colon definition, i M immediately prints the
string ♦ The string way not exceed 255 characters ♦
1EMTT
lPOSmON
1TYPE
n
Places the node 1 character with internal representation n on the screen, at the current
cursor position (see 1P0SITI0N) ♦ The character will have the color most recently selected
by the user* The cursor position is updated by 1 character*
x y —
Sets the current cursor postion to
will be placed at this spot*
x, y on a mode 1 screen 4 , the next character printed
addr c —
Places the string beginning at addr, with character count c, on a mode 1 screen starting
at the cursor position (see 1P0SITI0N) . The string will have the color most recently
selected by the user* The string must already be in Internal representation*
2EMIT
Used in the form*
r xxxx n
Compiles an in-line string xxxx, delimited by " (double quotes), along with the execution
procedure (l ,f ) which transmits the text to a node 2 screen (in the color most recently
set)* If executed outside of a colon definition, 2" immediately prints the string* The
string may not exceed 255 characters*
n —
Places the mode 2 character with Internal representation n on the screen, at the current
cursor position (see 2P0SITI0N)* The character will be printed in the color most recently
selected by the user* The cursor position is updated by 1 character*
2P0SITI0N
2TYPE
x y —
Sets the DJrrent cursor position to x, y on a mode 2 screen} the next character printed
will be placed at this spot*
addr n —
Puts the string beginning at addr, with character count n, on a mode 2 screen starting at
the cursor position (see 2P0SITIQN)* The string must already be in Internal
represenation, arid it will have the color most recently selected by the user*
Print in<3 Words , p*3
7"
Used in the for*:
m XXXX"
Compiles an in-line text string, delimited by M (double quotes) , along with the execution
procedure (7 M ) which, when executed, transits the text to a mfe 7 screen. The
characters have the appearance of node 2 characters} the full range of ATASCII characters
is available to the user* The string will be in the color nost recently set* If executed
outside of a definition, 7" causes the string xxxx to be printed iwtediately.
7EKET
n
Prints the character with Internal representation n on a node 7 screen* The character
will be in the color host recently selected by the user, and its upper-left corner will be
at the graphics cursor* The cursor will be updated by 8 pixels. The character will have
the appearance of a node 2 character*
7P0S3TI0N
x
Sets the graphics cursor to x, y on a node 7 screen*, the next *ode 7 character printed
will have its upper-left corner at this spot. Horizontally, characters Must start on byte
boundaries (every four pixels)} vertically characters nay start on any scan line.
7REL*SCRN!
nl n2 —
Stores the 16-bit value nl into the address which is rtZ bytes after the start of screen
nertory*
7REVERSE
— addr
A variable which holds an indicator as to whether node 7 characters should be printed
nornally or in inverse video* Contents=0 indicates normal, contents O 0 indicates
inverse.
addr n —
Places the text string beginning at addr, with character count n, on a node 7 screen,
starting at the graphics cursor (see 7P0SITI0N). The string will have the color rest
recently selected by the user} the characters will have the appearance of «ode 2
characters. The string mist already be in Internal representation.
CLEAR-TEXT-ODOW n —
Clears the first n lines of the text window,
text window is stored in TXTMSC.
Assunes that the starting address of the
HOLD-I
Inserts the character whose Internal representation is c into the pictured numeric output
string. For exanple, $E HQLD-I will place a decimal point into the next spot of the
output text* (Direct counterpart of HOLD*) Use only between <* and #>*
REL-SCRN! c n —
Stores the 8-bit value c into the nth byte after the start of screen Kenory*
SIGK-I
n d — d
Inserts the Internal value corresponding to (Minus sign) into the pictured nu*eric
output string (if n is negative)* (Direct counterpart to SIGN*) Use only between <* and
*>*
XV *7 Graphics Printing Words, p*^
T"
— (conpiling)
nl ri2 — (execution)
Used in the torn*
nl nZ T" xxxx"*
Cohpiles the irrline text string xxxx, delinited by " (double quotes), along with the
execution procedure (T")» Iflien executed, the string will be placed in the text window at
colum rdi row r»2* If executed outside of a definition, T n prints the string immediately*
TEMTF
n
Puts the character with ATASCII value n in the text window at the current cursor position,
position by 1 character*
TO. INTERNAL addr —
Converts the string beginning at addr, with a count stored in the first byte, fron ATASCII
to Internal representation*
addr c —
Prints the ATASCII string starting at addr, with count c, in the text
the current ojrsor posit ion*
at
WOFft-I c —
Reads the input strean until a deliniter c is encountered, Moving the text to HERE (with
the character count in the first byte), and converts the ted troa ATASCII to Internal
representation* (Direct counterpart to WORD*)
XPAtfttCQLQR nl — n2
Expands an 8-bit value nl (obtained fron the character set) to a 16-bit value rtZ for use
on a node 7 screen* Hhen placed on a node 7 screen, the bit pattern will reproduce 1 scan
line of a character in the color currently selected by the user. This allows characters
to be printed in node 7 using the character set. (Each bit of nl naps to two bits of n2}
bit x of nl naps to bits 2x and 2x+l of n2*, a 0 naps as 00, while a 1 naps as 00, 01, 10,
or 11, depending on the current color.) If 7REVERSE is non-zero* the ones conplenent of
ri2 is returned* allowing the printing of "stencil" characters.
Non-boot words used*. ATASCIDINTERNAL, INTERNALS ASCII, HAP.
The word CCOPY copies consecutive screens fro* sone given range to screens starting at a new
beginning nw*er. It's a smart copy routine, i*e* the new and old screens can overlap ♦
CCOPY Clstl Bast] Cnew 1st] —
Copies screens Cist] to Clast] to screens starting with Cnew 1st]
MCOPY wakes Multiple copies of a screen over so*e interval*
HCOPY Cist] Clast] Cscr, to be copied] —
rtak.es copies of Cscr, to be copied] over the screens in the interval
frcm screen Cist] to screen
IV*9 VERTICAL SCROLLING
Read chapter 6 (Scrolling) of De Re Atari for a discussion of scrolling on the Atari ♦
These words were created for use with Atari text nodes. The following procedure explains how to use
then*
W Load the vertical scrolling words* $ nust first be loaded fro* the Hiscellaneous Words*
2*. Create a display list, a portion of which has vertical scrolling enabled} this section should
begin with an LHS connand and it should not have nore than one LHS* The section should include one
nore node line than you wish to appear on the screen, and the very last display instruction in the
scrolling section should not have vertical scrolling enabled* (Thus, if 10 node lines of scrolling
graphics node 2 are desired, 11 erode 2 instructions should be placed in the display list, but only
the first 10 should have vertical scrolling enabled* See De Re Atari*)
Set up the scrolling variables* These aret
U5QRDLL4J6
Store the address of the nenory location in the display list which iiwediately follows the scrolling
section's LHS (i*e*, the address of the LHS address, which is the address of the start of the
scrolling display data) into this variable*
SCAN*LBES/U>E
This variable should be set to the value which is one less than the number of scan lines per node
line in the graphics node being scrolled* (Graphics node 2 (ANTIC 7) has 16 scan lines/node lire, so
the proper value for it is 15 ($F)5 graphics nodes 0 and 1 (ANTIC nodes 2 and 6) have 8 scan/lines
per line} the value for then should be 7*)
BYTES/LINE
This variable should contain the nunber of diplay data bytes per node lire in the graphics section*
This value is 20 ($11) for nodes 1 and 2 (ANTIC nodes 6 and 7), and 10 ($28) for node 0 (ANTIC node
4*_ Clear the scrolling registers by executing the word CLEAR* SCROLL* REGS *
At this point, scrolling should be enabled arid ready to go* Execution of the word IP will scroll the
text ore scan lire up} execution of the word DOWN will scroll the text one scan lire down*
Tining is crucial in scrolling* It nust happen regularly and it nust happen when the TV scan is
beneath the graphics area of the screen (otherwise, the scrolling will jerk arid the screen will
flicker)* For this reason, IF and DOWN nake sure that changes to the scrolling registers occur only
after the TV scan is beneath the screen by perforning a delay loop*, this prevents screen flicker* It
serves also to nake sure that scrolling occurs very regularly, as it can thus occur no faster than
every l/60th of a second (the tine it takes to "draw" the TV screen) , and as long as there are not
too nany routines between successive cells to UP and DOWN, it will occur no slower than every l/60th
of a second* (We have found that quite conplicated tests can be perfoned between successive calls to
UP and DOWN without slowing down the scrolling, so the user need not worry too nuch about this
problem)
The variables VSCROLL* COARSE* REG and VSCROLL* FINE* REG exist to allow checks as to how far in a given
XV *9> Vertical Scrolling, p*2
direction scrolling has proceeded; the values in these registers can thus be used to stop scrolling
at a given point. Bear in mind that both variables must be tested to see how far scrolling has
progressed* (Mote that, in addition to these two variables, the scrolling routines also change the
LMS address in the display list and the hardware scroll register,)
Here is a typical scrolling routine*.
: MERTICAL ♦ SCROLL ( — )
0 STICK DIP ( RETURNS STICK VALUE )
= ( UP )
IF
IP DRW
ELSE
* D = ( DOWN)
IF
DOWN
THEN
THEN ;
This checks the joystick arid scrolls up or down, depending on which direction the joystick., is
pressed. This word could then be used in a BEGIN ♦♦, UNTIL lew, or a similar loop, along with
various tests of the scrolling variables, to allow the user to scroll over text, up and down, using
the joystick..
The Vertical Scrolling
were
Brock A, Miller.
BYTES/LINE
— addr
A variable which contains the number of data bytes per node line in the current graphics
mode. Must be set by the user*
<3N
CLEAR, SCROLL, R
Sets the hardware arid shadow vertical scrolling registers (VSCROL, ^SCROLL
VSCROLL, FINE, REG) to 0, Used to initialize scrolling,
I.REG,
C0ARSE,D0WN
Performs a coarse scroll by decrementing the LMS address in the vertical scroll section of
the display list (pointed to by VSCROLL,LMS), It also decrements VS^IJLL. COARSE. REG by 1
arid sets the fine scrolling registers to their maximum values (contained in
SCAN, LINES AJ>E) ♦ The overall effect is to move text down one scan line on the screen.
COARSE, UP
Performs a coarse scroll by incrementing the LMS address in the vertical scroll section of
the display list (pointed to by MSCROLL.LMS). It also increments VSCROLL, COARSE, REG by 1
and sets the fine scrolling registers to zero, The overall effect is to move text one
scan line up on the screen.
Scrolls text one pixel down in that portion of the screen which has vertical scrolling
enabled ♦ Perf orris a fine scroll or a coarse scroll, as needed ♦
FTNE*D0WN
Decrements the vertical scroll register (VSCROL) by one, causing the text on the screen to
move one scan line down* Also decrements the shadow register (VSCROLL*FD£*REGh Waits
until the TV scan is off -screen to change the registers, in order to avoid flicker*
FBE*UP
Increments the vertical scroll register (VSCROL) by one, causing the text on the screen to
move one scan line up* Also increments the shadow register (VSCRIXL^FTNE^REG)* Haits
until the TV scan is off -screen to change the registers, in order to avoid flicker ♦
CFF* SCREEN* WAIT —
A machine code routine which loops until VCOL&fT, the TV scan line counter, indicates that
the TV scan is below the graphics area*, this is used before scrolling words to ensure that
scroll registers are not changed while the scan is on the screen*
SCAN*LDCS/LM: — addr
A variable which contains a value which is one less than the number of scan lines per mode
line in the current graphics mode* Must be set by the user* (e*g*, for graphics modes 0
arid 1, the value is 7} for graphics mode 2, it is 15*)
UP
Scrolls text one pixel up on that portion of the screen which has vertical scrolling
enabled* Performs a fire scroll or a coarse scroll, as reeded*
VSCROL — addr
A constant which contains the address of the hardware vertical fine scroll register
($CH05)* This is a ore byte, write-only register*
VSCROLL ♦ COARSE • REG — addr
A variable which contains the number of coarse scrolls performed relative to the starting
point of the scrolling*
VSCROLL* FINE. REG — addr
A varisbie which is used to shadow the hardware vertical fine scroll register (VSCROL) ,
which is a write-only register*
VSCROLL.LMS — addr
A variable containing the address in memory of the LMS address which is to be changed by
the scrolling routines (i*e* the address of the first byte of scrolling memory).
IV* 10 Playei — Missile Graphics, p ♦ 1
IV40 PLAYER — MISSILE GRAPHICS
The words preseriied here are easier to use arid Make code nore readable arid Maintainable thari
siMply writing to player-Missile and graphics registers* Nonetheless, the chapter in De Re ft tar i on
player-Missile graphics should be read carefully before using these words ♦
The first steps in setting up player-Missile graphics are to choose an address for the beginning
of player-Missile MeMory, choose either single- or double-line resolution* arid set the appropriate
bits in DHACTL and GRACTL* All of this is done by SET-P&M* SET-P&M takes two arguments off the
stack} the resolution (1 for single-line, 2 for double-line), arid the address of the start of
player-Missile MeMory, SETJF'&M then enables the players in DMACTL and GRACTL, sets the variables
MISSILE J, PLAYER J, etc ♦, and clears player-Missile MeMory*
With player-fiibsile graphics set up, the next step is to get something on the screen* Since the
Atari provides so Many special features, it way take several steps to forM any particular inage on
the screen* The first step is to store the inage in player-Missile MeMory (see De Re Atari page
4-3)* Setting the horizontal position of players arid Missiles can be do-* using HP0B!« HPQS! tak.es
two arguments off the stack* The first is the player or Missile nuMber - 0 through 3 for players 0
through 3*, 4 through 7 for Missiles 0 through 3* The second is the horizontal position, froM about $
50 for the left-hand side of the screen to $ 200 for the right-hand side* The widths of the players
and Missiles are controlled by SIZE!* which also takes two argunents off the stack.* The first is
again the player or Missile nuMber* This is 0 through 3 for players 0 through 3 respectively, but,
unlike HPOS! , all the Missiles are controlled by 4« This is because the sizes of all the Missiles
are controlled by one register, SIZEM, whereas each has its own horizontal position register* Bits 0
and 1 of SIZEM control the size of Missile 0, bits 2 and 3 Missile 1, etc* The second arguwent that
SIZE! tak.es froM the stack is the width*, 0 or 2 for single-width* 1 for double-width, or 3 for
quadruple-width* If SIZE! is used to set the width of the Missiles, they Must all be set at once*
For exaMplet
$ AB 4 SIZE!
will set Missile 0 to quadruple width, and the others to single-width*
The priority of objects on the screen (which object will appear to be "in front" when two
objects overlap) can be set by PRIORITY, which takes a nurtber froM 0 to 15 off the stack, and stores
it in the first four bits of GPRIOR* There are four basic priorities: 1 PRIORITY gives all four
players priority over the four playfield colors*, 2 PRIC&TTY gives players 0 arid 1 priority over the
playfield colors, which then have priority over players 2 and 3*, 4 PRIORITY gives all four playfield
colors priority over the players*, 8 PRIORITY gives playfield colors 0 and 1 priority over the
players, which have priority over playfield colors 2 and 3 (background color is always lowest
priority)* If priorities other than these four are used, objects with conflicting priorities will
appear black in regions where they overlap*
The colors of players and Missiles can be set by COLPM!* COLPM! tak.es two argunents*. the first
is the player nutter f 0 through 3 (Missiles take the colors of their respective players)*, the second
deterMines the color, 0 to $ FF* Fifth arid sixth player-Missile colors can be enabled using
CEL0RO3-P&M-0N (no stack effect)* After COLORED-PtthON is executed, where players 0 and 1, or
players 2 and 3 intersect, their colors will be CEed.
Use of the fifth player can be enabled by executing FIVE-PLAYERS (no stack, effect)* Note that
FIVE-F1AYERS only assigns the color of playfield color 3 to all the Missiles*, they Must still be
positioned together by the prograMMer*
ERASE-P&M will fill all of player-Missile Mewory will zeros, but art easier way to reMove players
and Missiles froM the screen is to set their horizontal positions to zero*
IV. 10 Plsyei — Missile
P .Z
AMD!
n addr —
Performs the logical and of the contents of addr arid n, leaving the result as the new
contents of addr* Used with both shadowed and unshadowed players arid Missiles*
CtLORED^aHHFF —
Disenables fifth arid sixth player-fissile colors*
Used with both shadowed arid unshadowed players and Missiles*
COLORED-P&M-ON —
Enables the use of fifth and sixth player Missile colors* Ifoen this is called, where
player 0 and player 1 intersect, arid where player 2 and player 3 intersect, their colors
will be ORed*
Used with both shadowed and unshadowed players and Missiles*
DISENAE1I-KISSILES —
Disenables the Missile graphics* Used only with shadowed players and Missiles*
DISENABLE-P&H —
Disenables player-Missile graphics*
Used only with shadowed players and
DISENAE1I-PLAYERS —
Disenables the player graphics*
Used only with shadowed players arid Missiles*
ENABLE-MISSILES —
Enables the Missile graphics*
Used with both shadowed and unshadowed players and Missiles*
ENABLE-P&M
Enables player-Missile graphics*
Used with both shadowed arid unshadowed players and Missiles*
ENABLE-PLAYERS —
Enables the player graphics*
Used with both shadowed and unshadowed players and Missiles*
ERASE-P&H
Stores zeros into all of player-Missile MeMory*
Used with both shadowed and unshadowed players and Missiles*
FIVE-F1AYERS
Assigns the color of playf ield color 3 to all the Missiles allowing theM to be Moved
together as a fifth player (otherwise, the Missiles take the colors of their respective
players)*
Used with both shadowed arid unshadowed players and Missiles*
IV* 10
P ♦ 3
FOUR-PLAYERS —
Assigns each Missile the color of its respective player.
Used with both shadowed arid unshadowed players arid Missiles*
FROH-SHADQH-f — addr
A variable which holds the address of the code routine attached just before
SHADOW-PLAYERS, The paraMeter field of FRQH-SHADOW-P Must not cross a IK boundary,
GENTLE-GR, graphics * —
Switches graphics Modes without bothering the players and Missiles,
Used with both shadowed arid unshadowed players and Missiles,
GRAFPO — addr
A constant that returns the address of player O's graphics register. Used with both
shadowed arid unshadowed players arid Missiles,
HPOS!
HPOSPO
HISSILEJ
NOT
OR!
PLAYERJ
PLAYERS
x n
Moves player n to the horizontal position x on the screen.
This word is used both with shadowed and unshadowed players and Missiles,
— addr
A constant that returns the address of player O's horizontal position register, Used only
with shadowed players and Missiles,
— addr
A variable which contains the address of the beginning of Missile Memory.
This word is used in both shadowed arid unshadowed players and Missiles.
n — m
Returns the ones coMplewent of the top of the stack.,
n addr —
Per for ms a logical or on the contents of addr and the value n. Leaves the result as the
new contents of addr. Used with both shadowed and unshadowed players and Missiles.
— addr
A variable which holds the address of the beginning of player O's Mewory. SiMilarly for
PLAYER.l t PLAYER.2, etc.
These words are used with both shadowed and unshadowed players and Missiles.
— addr
A variable which contains the address of the beginning of Missile Memory. This is the
saMe as HISSILEJ, but it will Make code clearer if this is used when FIVE-PLAYERS is
enabled.
This word is used with both shadowed arid unshadowed players and Missiles.
PM-RESOLUTION n —
Sets player-Missile resolution} takes either n=l for single-line resolution or n=2 for
double line.
This word is used with both shadowed and unshadowed players and Missiles.
PMBASE-SHADOW — addr
A variable which holds the page nuwber of the beginning of player-Missile MeMory.
This word is used with both shadowed arid unshadowed players and Missiles*
S-HPOSPO
S-SIZEPO
SET-P&M
PRIORITY n —
Sets the bit in GPRIOR which controls the priority of objects on the screen* An object
with higher priority will appear to be "in front" of an object with lower priority*
Used with both shadowed and unshadowed players and Missiles*
— addr
A constant which contains the "shadow" registers for the player-Missile horizontal
position registers HPQSPO, HP0SP1, etc*
Used only with shadowed players and Missiles*
— addr
A constant which contains the "shadow" registers for the player-Missile size registers
SIZEPO, EEEP1, etc*
Used only with shadowed players arid Missiles*
addr* n —
Enables player-Missile graphics* setting the start of player-Missile MeMory to addr, and
the resolution to n* SET-P&M also sets variables MISSILE J, PLAYER J* PLAYER.lt etc*, and
clears player-Missile MeMory*
Used with both shadowed and unshadowed players and Missiles.
SETUP-SHADOW-P&K —
Attaches SHADOW-PLAYERS to the iMMediate MBLANK routine. SETUP-SHADOW-P&M Must be
re-enabled after a reset.
This word is only used with shadowed players and Missiles.
SHADOW-PLAYERS —
A MELANK routine that reads values froM the "shadow" registers S-HPOSPO and S-SIZEPO to
the player-Missile horizontal position and size registers. SHADOW-PLAYERS also shadows
the graphics control register GRACTL in S-GRACTL.
This word is only used with shadowed players arid Missiles.
SIZE!
size, n —
Changes the width of player r»* Width will be either single width (size=0 or 2), double
width (size=l), or quadruple width (size=3)*
This word is used both with shadowed and unshadowed players and Missiles*
WAIT-UB
Waits for the next vertical blank, arid returns control after interrupt ends. Used only
with shadowed players and Missiles.
^^^^^^
IV* 11 SHADOWED PLAYERS A.JSLTD
Chris Helck of the Swarthaore Trigonometry Project designed a set of "shadowed" player-rtissile
words to correct two problems which occur when using unshadowed players and rtissiles* The first of
these happens when display list interrupts are used to display a player in two (or wore) parts on the
screen* With unshadowed players, this requires two display list interrupts, one in the Middle of the
screen to change the players horizontal position, arid one at the botton or top of the screen to set
it back to its original position* Shadowing the horizontal position registers rtak.es only one display
list interrupt necessary* The second problew is that HPOS! writes directly to the horizontal
position register* As a result, if it is being called while a player is being drawn, the botto* part
of the player will hove before the top, producing, briefly, a ragged line, ratter than a straight
line* Shadowing the players renoves this problem In addition to shadowing the horizontal position
registers, SHADOH-PLAYERS also shadows the size registers arid GRACTL*
In order to use the shadowed players, the only extra step is to call SETUP-SHAD0I4-P&M (no stack-
effect) after each RESET* All of the urr-shadowed player-missile words have the sane function in the
shadowed words*
The vertical blank routines nust be loaded before loading the shadowed player-trissile words.
i
IV + 12 TEXT WORDS FOR DISK STORAGE
OF TEXT
The text words provide 3 convenient Method of storing blocks of text on disk, arid noving then
easily into nenory* The text is included in the definition of words defined by *T (for node 0 text)
or ST12 (for Modes 1 or 2 text)* The text nust begin on the line following the IT (or **T12), and the
end of the text is signaled by a seni-colon at the beginning of a line* For example}
JT GEORGE
This is the text which
is being stored in this
example called GECff\*GE
;
The text in words defined by *T12 should not have nore than 20 characters to a line J characters
beyond the 20th are ignored*
The text can be any nutter of lines long* If the text will not fit entirely on one screen*
sinply write to the botton of the first screen and continue at the top to the next screen* Do rat
use a " y •
Wren a text word is compiled (i*e* the screen containing it is loaded) ♦ the definition in the
computer lienor y does not contain the actual text* Rather* it contains a pointer to the screen on
which the text is stored* Thus, when the word is executed it is essential that the disk containing
the text is in the disk drive*
When 3 text word is executed it expects an address on the stack* arid it noves the text fro* disk,
to nenory beginning at the given address. Since the primary use of the text words is to wove text on
to the video display, there are three words designed to return the appropriate address*
n HlhDCfrHJhE returns the address of the nth line of the text-window (assuring one is in use)*
n SCREEN-LINE returns the address of the nth line of a node 0 screen, while
n SCREEN-LINE12 does the sane for node 1 or 2 screens. In all cases the top line is nunber 0*
Thus
3 SCREEN-LINE GEORGE
would put the text in the definition of GEORGE on a node 0 screen, beginning at line 3 (i.e* 4th line
fron top).
To increase flexibility, the pointers that are conpiled into text words are not the absolute
screen nunber s on which the text appears, but are instead offsets fron the screerr-nunber stored in
the variable TEXT-BASE. It is therefore necessary to put the word INITIAL-TEXT-SCREEN at the top of
the first screen which contains words defined by # *T or !T12* This sets the variable TEXT-BASE to the
correct value*
*
The advantage of this systen cones fron the fact that it is sonetines desirable to load a
progran fron one disk and store the text on a seperate disk (this is especially true if the progran
is preconpiled)* To do this, sinply reproduce the screens containing text words on the text disk.*
Hake sure that they are in the sane order and relative position as they are on the progran disk* It
is not necessary, however, to put the text on the sane nunhered screens* Instead, store the nunber
of the first text screen (the one that contains the word INITII^-TEXT-SCREEN) in the variable
TEXT-BASE*
IV. 1Z TEXT WORDS, P. 2
It is sonetines desirable to bring a screen containing text into the buffer at socie point before
the text is actually used (so that the disk, drive does not have to operate at that point). This is
done using the word TEXT-BUFFER. For example, if GEORGE is a text word, the expression
S BUFFER-EXAMFIE
' GEORGE TEXT->6UFFER
♦
i
will bring the screen containing GEORGE'S text into a buffer* Note the fornat carefully? first a '
(tic), then the teat word, then TEXT->BIIFFER*
One final note 5 all of the text words are designed to use 4 space Margins in node 0 (32
character lines) • This is particularly easy to work with when the GE editor is enployed.
. The Text Words were prograiwed by David Fristrow.
TEXT->BUFFER pfa —
Calls frott disk to buffer the screen containing the text word with the given pfa* Usually
used in the fornatt
' XXXXX TEXT-/RFFER
where XXXXX is a word defined by JT or tT12,
HODEO — addr
A variable used as a flag by the text words*
1ST) fig —
The nain component of JT and 5T12« A defining word* Compiles fig (l=*»ode 0, 0=«ode 1 or
2), screen nunber of text (counting frow TEXT-BASE), and line nunber of first text lire.
During run tine, words defined by (*T) nove text froh disk, to nenory, beginning at the
address on the stack (usually sone part of screen nenory).
JT
A defining word, used in the forhat \
}T XXXXX
The text which you want to store on disk
5
Hote that the seni-colon mjst be at the beginning of its line. IT compiles into the
definition of XXXXX a flag to indicate the text is in graphics node 0, the nunber of the
disk screen the word is defined on (counting fron TEXT-BASE), and the nunber of the screen
line on which the text begins. Words defined by IT are used in the format*,
addr XXXXX
This woves the text fron the disk to nenory, starting at addr.
IT12 is the graphics nodes 1 and 2 equivalent to *T* It is identical to **T except it
compiles a flag indicating Mode 1 or 2 rather than node 0* Because node 1 or 2 characters
are wider than node 0, the text should not exceed 20 characters to a line*
mmftL-TEXT-SCREEN —
Stores the value of BLK on TEXT-EASE. It should be used at the beginning of the first
source code screen which contains definitions of text words defined by JT or JT12.
JT12
12 TEXT WORDS t P*3
SCREEN-LUC n — addr
Returns the address of the nth line of 3 graphic Mode 0 screen (with top line being zero).
SCREBMPC12 n — addr
Returns the address of the nth line of a graphic node 1 or 2 screen (with top line being
zero) ♦
TEXT-EASE —addr
A variable used by the text words to contain a pointer to the first disk screen which has
words defined by tT or JT12 on it*
HI1COHJME n — addr
Returns the address of the heginring of the nth line of text
zero) ♦
(with top line being
IV + 13 TEXT COMPRESSION TEXT WORDS
Effective use of text on the TV screen requires a great deal of waste space* Readability is
enhanced by writing in short phrases rather than 40 character lines, by small paragraphs, generous
indentations, and by writing only or. every other line* The Text Compression Text words allow you to
get by with this without exacting a price in disk storage - typically we have 1/3 to 1/4 as many
compressed text screens as "source" text screens* These words also allow the same hardy Manipulation
of text as do the regular Text Words*
In general, you would use the regular Text Words when developing an application (please see
Section IV* 12)* Text Compression text Words are used in exactly the sane fashion as regular Text
Words, arid no changes need be made with two exceptions 4 * (1) The word END-TEXT Must be added
immediately following your last JT or 5T12 word* (2) You can force the usage of a new text screen
(in order, for example, to avoid disk operations at an infelicitous time) by inserting the word
NEW-SCREEN before a 11 or ST12 word*
To make up a disk using the Text Compression Text Words, just load those words (FORGET ting the
regular JT words, if necessary). Then choose a screen number for the first screen of compressed text
and store it in TEXT-BASE # Subsequent screens will be filled downward from this - we fill disks with
compiled code upward arid compressed text downward* If you prefer your screens to be filled in
increasing order, instead, there is an obvious change you can make in MCWE.TO*DISK arid one in
NEXT .SCREEN*
-
Now load yoi.tr JT and JT12 words* Various messages will inform you of the progress of the
compilation, terminating in "END TEXT COrPHATION" ♦ Proceed to load your non-text words, as in the
regular Text Word context*
Behind the Scenes
The Text Compression Text Words work as follows* When compiled there is an Encode Buffer which
requires $420 bytes starting at EBUFF* START (currently set to $A400 - change if you're already using
that area of memory)* Compressed text is collected in the Encode Buffer in contiguous strings of the
form*.
bbnncccc***c
where bb is the number of blanks to be written to screen, rm is the number of characters following,
arid cccc***c are those characters in Internal form* Thus, decoding consists of writing the specified
number of blanks arid then CMOVEing the character string to screen memory* Setting the number of
blanks bb to -1 is used to signify that the next screen of compressed text is to be brought in* For
example when the Encode Buffer has been filled everthing up to the overhanging string is sent to the
FORTH buffer arid a -1 is tacked on at the end.
The end of a **T or !T12 word is indicated by placing a 0 in the "number of characters" slot rm*
A text word defined by IT or 5T12 returns an address to a table containing the screen offset,
character offset in the screen, and a Mode 0? flag*
These words require $ from the Miscellaneous Words*
IV* 13 TEXT COMPRESSION WORDS t p +
— addr
Variable which holds the nunber of characters which are neither leading nor trailing
blanks in a line of text on a CE screen ♦
— addr
Variable which holds the nunber of leading blanks in a line of text on a QE screen*
♦LEADING
addr — count
Calculates the nunber of leading blanks in the text line starting at the given buffer
address ♦
— addr
Variable which holds the nunber of trailing blanks in a line of text on a QE screen*
(IT)
conpilet flag —
run' addr —
At compile tine this defining word encodes a ST word for hode 0 if flag is 1, arid Hode 1
or 2 otherwise* At run tine, the word is decoded starting at screen nenory given by addr*
Defining word which at conpile tine ericodes text word with line length arid nargins set for
Hode 0* At run tine the text word decodes at the nenory address on top of the stack*
Defining word which at conpile tine encodes text word with line length arid nargins set for
Hode 1 or 2* At run tine the text word decodes starting at the nenory address on the top
of the stack*
B.LINE
Encodes a line of blanks (i*e*
B.PTR)*
nunber of blanks to the value at H*PTR and updates
B.PTR
c
— addr
A variable which during encoding holds the address in the Forth disk buffer (between $500
arid $CF) of the next text character to be encoded* During decoding it points in the
Forth disk buffer to the next text character* or to numeric infornation between character
strings*
IV* 13 TEXT COMPRE
t P ♦ 3
DECODE
addr flag s.off c.off —
Takes screen given by offset s*off and reads to Forth buffer, sets B*PTR fro* BLOCK and
offset c*off . DECODE* LINE starting at addr until EOT? is set to 1. Compiled for Hode 0
if flag is U
DECODE* LINE
Writes on the TV screen the nunber of blanks stored at B*PTR t then CMQVE the number of
characters stored at B.PTR+2 arid starting at B.PTR+4. If 0 characters, set EOT? to 2.
EE1IFF* START — addr
Constant pointing to beginning of the IK Encode buffer*
ENCODE
Encodes text of a »T word until a "}" is encountered as the first character in a line on a
QE screen*
ENCODE* CHARS r. —
ttoves next n characters fron Forth buffer to Encode buffer* and transforms fro* AT ASCII
to INTERNA* Increases pointer in both buffers by n.
ENCODE. LINE
EhD*
Encodes a line of text fro« the Forth buffer and moves IN to the next line*
Stores 3 0 in the "nuttber of characters" position in the Encode buffer and troves M.PTR in
positon for new word,
END-TEXT
EOT?
Placed by user after last ST word to send final contents of Encode buffer to drive,
Prints "END TEXT ENCODING" on TV screen,
— addr
Variable containing flag which indicates the end of a JT word*
INTiTAL-TEXT-SCREEN —
Placed by user prior to 5T text words to initialize S.CfFSET and M.PTR. When coMpiled it
prints Message "START TXT ENCODING".
(
LINE, LENGTH
Variable indicating the length of the line of QE screen to be decoded (32 for Hode 0, 20
for Modes 1 and 2) .
IV* 13 TEXT COMPRESSION WORDS, p* *
L* MARGIN — addr
Variable containing the nurtber of characters in the left Margin of the TV screen for
decoded text (0 for Modes 1 and 2 f 4 for Hode 0).
MOVE*TQ*DISK —
Hoves encoded text fro* Encode buffer to Forth buffer and UPDATE* Prints Message "TS n"
on the video screen arid subtracts 1 frm the contents of S* OFFSET*
H*PTR — sddr
Variable used during encoding to store the current offset position froM EBUFF* START in the
Encode buffer* During decoding it points to the next byte in screen MeMory*
ffiXT* SCREEN —
Called by DECODE to read in the next encoded text screen froM disk if the "nuhber of
blanks" position in a ericoded line is negative*
Placed by user before a JT word (or JT12 word), this will cause the word to be encoded on
a new text screen* Inserted by user if previous compilation of JT words has resulted in
inconvenient disk read (e*g* in the Middle of the following word)*
NXT*SCR? —
Checks whether B.PTR is beyond the Forth buffer in which it started and, if so* brings in
the next text screen to reset B*PTR*
NONB.LINE —
Encodes a non-blank lire of text and updates pointers*
OVERFLOW —
Takes the Encode buffer up to the current line and HOVE* TO* DISK* Hoves the current
encoded line to th top of the Encode buffer and sets M.PTR to the end of the line*
R*HARGIN — addr
Variable containing the nunber of characters in the right Margin of the TV screen for
decoded text (0 for Hodes 1 and 2, 4 for Hode 3)*
H_IhE n — addr
Returns Menory address addr of line n of Hode 0 screen MeMory (ft = 0,1,2, ♦♦♦)♦ Thus, if
TEXT is the nane of a tT word, then*
2 SCREEN-LDC TEXT
will decode TEXT starting at line 3 of the TV screen*
P • 5
SCREEN-LINE12 n — addr
Returns nenors address addr if lire n of node 1 or 2 screen *e*ory (n * 0,1,2,...). Thus,
if TEXT12 is a JT12 word then*.
2 SCREEN-LDC12 TEXT12
Hill decode TDCT12 starting at line 3 of the TV screen.
SET, MODE flag —
The flag is 1 for node 0, 0 for Modes 1 and 2, L. MARGIN, R. MARGIN, and LINE. LENGTH are
set accordingly.
S. OFFSET
— addr
Vcriable giving offset frow ojrrent screen to TEXT-BASE.
TEXT-BASE — addr
A variable set by the user to the first (arid highest numbered) screen to be used for text
storage ♦
HINDOVKIHE r. — addr
Retruns nertory address addr of line n in text window (n = 0,1, 2, or 3) for the standard 4
line text window) ♦ Thus, if TEXT is the mm of a !T word then!
2 HBTOHIhE TEXT
will decode TEXT beginning at line 3 of the text window.
See the Atari OS manual for more information on the VBLANK process*
The Swarthmore Trigonometry Project VBLAW attaching words were developed to solve a problem
which may occur when attaching code routines to the immediate or deferred VBLANK routines - by
storing addresses in WBLKI or WBLKD* IF VBLAW occurs while the routine is being attached, it is
possible that only half of the address of the routine will be updated, and the machine will crash*
These words are a safeguard against this problem*
To attach a routine to the immediate or deferred VBLA1& routines, first be certain that the last
thing your routine does is jump to the previous initial VBLAI& routine (the address of this routine
can be fetched from WBLKI for immediate or WBLKD for deferred routines)* Then, put the address of
your routine on the stack and execute either STARTH)EFERREI>-^ or STl«T-IWEDIATE-VEW* To detach
routines, simply execute either NO-MEDIATE-VE^ , or WH)EFEFmHflEV. Note, however, that these will
only detach the routines which were atached after IVBLKI and IVBLKD were compiled, i*e* after the
VBLANK screens were loaded*
START-DEFERFOHW addr —
Attaches the machine code routine starting at addr to the deferred VBLAW routines* The
new routine will now be the first deferred VBLANK routine to execute* It is assumed that
the new routine already ends with a jump to the previews initial deferred routine}
otherwise, the system will crash.
START-IKMEDIATE-VBV addr —
Attaches the code routine starting at addr to the immediate VBLANK routines* The new
routine will now be the first VBLANK routine to execute* It is assumed that the new
routine already contains a jump to the previous initial VBLA$< routine*
IVBLKD — addr
Returns the starting address of the code routine which was the first deferred VBLAW
routine at the time that IVBLKD was compiled*
IVBLKI — addr
Returns the starting address of the code routine which was the first immediate VBLANK
routine at the time IVBLVKI was compiled*
NO-DEFERREIH^ —
Detaches all deferred VELANK routines from the VBLAW process, except for OS routines and
routines which were attached before IVBLKD was compiled* See IVBLKD*
NQ-IMHBIATE-VBV —
Detaches all immediate VBLANK routines from the VBLANK process, except for OS routines arid
routines which were attached before IVBLKI was compiled* See IVBLKI*
IV.15 Big WTOBJ
This version of HTOBJ works exactly the same way as the version described in Section HI A*
except that it can create boots of rare than 255 sectors* The source code for this version is also
in a Much wore readable form
The word SOUND is adequate for many sound generating pur poses, but in some instances it leaves
much to be desired. Specifically, if the sound to be produced is to vary dynamically (change volume,
Pitch, or timbre over time) or if it has to persist for only a certain amount of time, then the
processor will be tied up and will be unable to do anything else during the duration of the sound*
This means that (for example) dynamic sound arid graphics are impossible to produce simultaneously
with SOUND*
If internet-driven sound routines are used, however, this limitation disappears* A basic
interrupt-run sound system consists of several words* There is a word that takes parameters for a
note from the user arid loads these parameters into sound variables* These variables correspond to
pitch, timbre, volume, and duration (for each of the four sound channels)* Another word (written in
assembler) is set up to run in VBLANK* This word moves the sound parameters from the variables to
the hardware sound registers* If a duration parameter is being used, this interrupt ' routine would
also decrement a duration counter every UBLANK (i*e*, every 1/60 second) arid shut off a channel when
that counter reached zero. A more involved sound routine that read from a table of sound parameters
would allow timbre or volume changes during the course of a note*
See De Re chapter 7 for more information on sound routines.
IV ♦ 17 QE Users Manual , p ♦ 1
IVJ7 QE USERS
Introduction
C£ is 3 full-screen text editor t designed and programmed by Charles A. Clinton* Written in
FORTH, it was created primarily for the entering and manipulation of FORTH text, but it cari easily be
used to enter and manipulate text for other purposes* It is large (about $2200 bytes of memory), but
we find it sufficiently convenient that we include it in our boot* We provide both source code and a
glossary, so enterprising programmers can modify the editor to their own tastes*
•
Because of the size of the Atari screen, 24 rows of 40 columns, one disk, "text screen" of 1024
characters cannot fit entirely on the editor screen* The editor will only display 22 lines of text,
but will allow you to enter data or. 32 lines* The two extra rows at the bottom of the screen are
reserved for the prompt line, explained below*
The editor screen can be scrolled over the text screen* When you scroll the screen up, the
text at the top will disappear, but it has not beer, lost as it would be with the fig EDITOR*
.
Loading QE
The disk "Swarthmore GE" contains GE in the boot.
To load QE if it is not in the boot, it is necessary to first load $, ATASCmiNTERHAL, and HOME
from the Miscellaneous Words, IV* 1* Then, one must add on IV* 3 CASE, IV* 4 Display List Assembler,
and IV. 10 Unshadowed Player Missile Words. Then the source code for QE can be loaded*
Beginner's Walk Through
This section contains the basic instructions which you will need. Further commands, are
explained in later sections of this manual. Let us suppose that you have booted with a disk which
has QE in the boot arid that you have inserted a formatted disk to use for practice. To enter GE,
merely type in QE arid press return. The screen will flash, arid there will appear a line at the
bottom of the screen which says, something like "GE 0.1.1 18-June-B2". The number at the right end
of this prompt line is the screen that you are or. ♦ In order to get to another screen, first type
the letter S.
The prompt line will now say, "Re Wr Ne Lk Ulk ?" and will have the screen number at the end of
the line. Type in the new number you want, 45 for instance. The number 45 will replace the earlier
number. Now type in "R" to read that screen from the disk. After a moment while the screen is being
read, the bottom line will change to "Command". How, if for example you want to clear the screen,
type "T", then "D", then "A". This will move your cursor to the top of the screen, put you into
Delete mode, arid then delete the rest of the screen by filling it with spaces.
After having cleared the screen let us enter new text in Insert mode. Type in "I". The word
"Insert" will appear or. the prompt line, arid the borders of the screen will turn red. These will
stay red as long as you are in either Insert or Overwrite modes. How, if you enter text, it will
appear or. the screen as if you were using a typewriter.
Until you use up all 32 lines of the FORTH screen, a new blank, line will appear when you reach
the bottom of the page, arid the top line will disappear. You will know you've completely filled a
IV* 17 QE Users Manual , p*2
screen when no wore blank lines appear.
Overwrite node is sometimes better than Insert Mode for editing existing text, so try switching
modes, either by holding the CONTROL button down while typing Wi or by hitting the ESC button,
which will put you back, in Command mode (notice the bottom lire), and then typing IT. In either
case, "Overwrite" will appear on the bottom line* You can nove your cursor about with the arrows,
used while holding the CONTROL button down, or by other commands explained in the Insert and
Overwrite section of this manual. Wien the cursor is in the correct place, you can type over the
existing text*
When you are in Insert node, new characters are inserted between the cursor and the next
character* In Overwrite node, hitting the carriage return will take you to the next line} in Insert,
it will create a new line below the present one*
When you are finished your editing, press the ESC button to return to Command node* Fro* here,
go back again to Screen node by typing "S". If you now type "H", the screen you are on will be
written to the disk* One nice option that Screen mode has is that you can type "N", and the screen
you have been working on will be written to the disk, and the or* after it will be read in fro* the
disk* Once you've typed an "N" or a "W", you will be put back into Comand node. To quit the editor
type "Q".
Another convenient way to enter the editor is to type the number of the screen you want to start
with, and then type "SE"* Hore detailed information on the various modes follows*
Command Hode
In order to reach any other mode while in Comand node, type the first letter of the node's
name** "S" for Screen node, "D" for Delete node, "I" for Insert node, arid "0" for Overwrite node.
To escape back to Comand node hit the ESC key. Nornally, one should return to Comand node when not
actually entering text*
Command node is useful for elementary text Manipulation (e*g. typing "B" will break ore line
into two? typing "X" will join two lines into one) and also for fast cursor Manipulations*
Tab keys nove the cursor horizontally to tabs set eight spaces apart* Tab itself will nove the
cursor to the right, while "A" will nove the cursor to the left* To clear a tab nark, hit Shift Tab 4 ,
to set a tab, hit <CTRL> Tab* You can jump to the next word by hitting "H", or to the end of the
lire by hitting "E", to the end of the text by hitting "Z", or to the top of the tod by hitting "T u *
It is possible to scroll the screen up or down in two different ways* If the cursor is at the
top of the screen arid you hit either <CTRL> up-arrow or "U" the screen will nove up, exposing the
line of text "above" the screen ♦ Symmetrical commands hold at the bottom with <CTRL> down-arrow or
"H"* Hit "Y" to scroll the screen up, or "N" to scroll the screen down* Note that when you reach
the last line of text at the bottom or the first line of text at the top, the screen will no longer
scroll, but rather will flash and beep at you*
In all modes, capitals and lower case commands have the same function, so that, for example, "S"
and "s" will both put QE into Screen mode.
Command Mode Commands
Users Manual , p * 3
"T n - Hoves cursor to first line of text screen*
"Z" - Hoves cursor to last line of text screen*
"W" - Hoves cursor to beginning of next word*
"E" - Hoves cursor to end of current line*
Tab - Hoves cursor to next tab nark*
"A" - Hoves cursor to next tab wark to the left*
Shift Tab - Sets a tab nark in current cursor position*
<CTRL>Tab - Clears a tab nark fro* present cursor position*
<CTRLMJp-Arrow - Hoves cursor up one line*
<CTRL>Dowrr-Arrow - Hoves ojrsor down one line*
<CTRL>Left-Arrow - Hoves ojrsor left ore
<CTRL>Right-Arrow - Hoves cursor right one character*
ll H" - Sane as <CTRL>Left-Arrow*
For this and the three commands that follow ♦ notice the convenient
the keyboard*
"J" - Sane as <CTRL>Right-Ar row ♦
"IT - Sane as <CTRLMJp-Arrow*
"H" - Sane as <CTFl>Dowrr-Ar r ow
<Return> - Hoves cursor dowri one lirre to first non-space character*
<Break> - Sane as <Return>*
T* -Scrolls screen up one line*
M N" - Scrolls screen down one line*
"I" - Shifts GE to Insert node*
"D" - Shifts GE to Delete node*
"B n - Breaks the current line at the cursor position.
"X" - Joins two lines together*
"Q" - Exits fro* QE*
of these keys on
IVJ* 17 QE Users Msriual* P
Screen Hode
Screen node is reached through comand node by typing "S". It is intended for the handling arid
Manipulation of entire text screens, arid for accessing the disk* This is accomplished by usirig a
combination of nine letter cowhands, and the ten digits at the top of the keyboard* Entering
anything besides these nine elands or the digits will cause you to return to Cohnand node. ESC is
the dignified way of returning to CoHnand node*
Three of the cowiands in Screen node are for the nanipulation of the screen number* Typing a
,, + n will add 1 to the screen nunber} typing a n - n will subtract 1 fron the screen number } V is used
to change the screeri rwnber to 0* You can't type in a negative number, arid if you want to access a
negative screen, you Must go to 0 and keep the "-" pressed down until you reach the desired screen
nunber ♦
There are three cowhands in Screen node which have to do with "locking" screens* This "lock" is
harked or. the disk, and it tells QE that the screen involved should not be written to, though it way
be read out into the editor* The three comands are "L", which will lock the screen you are on
(according to screen nunber), "U", which will unlock the screen yew are on, arid "?" which will tell
you whether a screen is locked or rot by putting the word "LOCKED" or "UNUJCKED" in the prompt line*
This "locking" systew is only effective with QE, not with the fig Editor*
(If you want to either "lock" or "unlock" every screen on the disk, you nay do so fro* outside
QE* Type the drive nunber, a space and IM.0CK.ALL or LQCK.ALL to do this*)
The last three cowhands in Screen nude are for the actual accessing of the disk.* These are 4 * "R"
which reads frow the disk, the screen corresponding to the screen rxuhber on the proapt line, "W",
which will set a flag for writing the revised screen back, onto the disk (unless it is write-protected
or "locked"), and "N", which writes the present screen to the disk, adds one to the screen nuhber,
and reads this next screen back, out into the editor* If the screen is "locked," this will cause an
error arid put the editor back in Comand hode*
Hotet "H" and "N" do not cause iiwediate writing to disk* To nake sure the last two screens you've
worked on are actually written to disk, type FLUSH after you exit the editor*
Screeri Mode Cowhands
"L" - Locks the current screen to prevent inadvertently writing over it*
"U" - Unlocks the current screen to allow writing it to disk*
"?" - Checks to see whether the current screeri is locked or not*
"R" - Reads the current screen fro« the disk*
"W" - Writes the current screen to the disk (but see above note).
"N" - Writes the current screen to the disk, and then reads the subsequent screen fro* the disk.*
"+" - Adds 1 to the current screen nurtber*
"-" - Subtracts 1 fro* the current screen number*
IV* 17 QE Users Manual f p *5
V - Changes the current screen nunber to 0*
Screen numbers can also be entered directly, using the digits at top of keyboard. (Negative nurters
can only be reached by subtracting fro* 0.)
ESC - Returns EE to Cowhand node*
Delete Hode
Delete node is different fro* the other nodes in GE in that or* camot stay in the node but can
only use it for one cofwand at a tine. This gives the user the feeling of having two letter comands
instead of one* For example, to delete a line while in Cowhand «ode, you type '"DL" ♦ The "D" puts
you in Delete f*xte, the M L H tells QE to delete the line the cursor is on, then CE puts you back into
Cowhand node.
Delete Mode can be reached fro* Comand, Insert, arid Overwrite, arid it returns to the node fro*
which it was called* Thus, if one is in Insert node arid types <CTRL>"D" f which is the way to reach
Delete rtode fro* Insert node, one would enter Delete node, but upon leaving would return to Insert
node* (In any other node either an error or EX returns one to Comand node.)
Delete node has six cowards besides the ESC key. Four are for basic editing! H C n deletes the
character the cursor is on arid pulls back, the other characters on the line to fill in} "S" deletes
all the spaces between the cursor arid the next non-space character? "W" deletes the rest of the word
following the cursor.
The other two cot-wands are a little different. "A" clears everything on the screen after the
cursor, and "B" clears everything before. They are intended for wajor editing, so "B" deletes all
before the cursor by filling in spaces, instead of pulling back, the rest of the text to fill in the
deleted lines and letters. To clear a screen, Jump to the top or bottoa of the screen and type "D"
arid either "A" or "B" depending on whether you are at the top or bottom
p ♦ <£>
Delete Hode Comands
(
"A" - Deletes all text after the cursor*
"B" - Deletes all text before the cursor*
H C M - Deletes the character the cursor is on? pulls back, the rest of the line to fill in.
V - Deletes the line the cursor is on} pulls up the lines below to fill in the e«pty lire*
H S" - Deletes all spaces fro* the ojrsor to the next non-space character} pulls rest of lire back, to
fill iru
"W" - Deletes word or part of word, frcw cursor onward, pulls rest of line back, to fill in*
ESC - Returns to previous Mode*
XV ♦ 17 QE Users Manual t P ♦ 7
Irisert ttode and Overwrite Hode
•
There are two nodes in CE for entering and editing text directly* Insert node and Overwrite
node* They have nany connands in connon, arid other connands which are very sinilar* The nost
inportant difference in the two nodes is that Insert node inserts text, while Overwrite node writes
on top of existing text. If you hit the return key in Insert node, a new line will be inserted (if
there is roon on the screen), but hitting the return key will just nove the cursor down in Overwrite
node* Also, if you are in Insert node arid start typing in the Middle of a sentence, the rest of the
line will nove aside as you type, whereas in Overwrite node the old text will be overwritten*
Aside fron this difference, nost cowhands in Insert and Overwrite nodes are the sane* The
arrows can be used, in conjunction with the <CTRL> key, to hove the cursor about the screen, arid nost
of the connands which are found in Cowand node (e*g* H T" to nove to the Top of the text screen) can
be used in these two nodes by holding the <CTRJ> key down while typing the conwand. Added to these
connands are a few special ones, Shift INSERT and <CTRL> INSERT, the first of which inserts a space
after the cursor, the second of which inserts the next character typed after the cursor* The
advantage to the latter is that an^ character nay he inserted, including control characters which
can't be entered via nornal text editing*
<CTRL> "D H will put you into Delete node* (As explained in that section, Delete node will
return QE to Insert or Overwrite node if it is called fron there)* <CTRL> T 1 will transfer CE to
Insert node fron Overwrite node, <CTRL> "0" to Overwrite node fron Insert node. Thus, you do not
need to go through Connand node to switch between these two*
IV ♦ 1Z QE Users Manual * p ♦ 8
Insert Hode Cwmands
<CTRL> n T" - Hoves cursor to first line of text screen*
<CTRL> , 7" - Hoves cursor to last line of text screen*
CTRLyW 1 - Moves cursor to beginning of next word*
<CTRL> U E" - Hoves a.»rsor to end of current line*
Tab
- Hoves ttirsor to next tab nark*
Shift Tab - Sets a tab nark in current cursor position*
<CTRL>Tab - Clears a tab nark fro* present cursor position*
<CTRL>Up-Arrow - Hoves cursor up one line*
<CTRL)-DowrrArrcw - Hoves cursor down one line*
<CTRL>Left-Arrow - Hoves ojrsor left one character*
<CTfORight-Arrow - Hoves cursor right ore character*
<Return> - Adds line beneath current line arid places cursor at sane indentation as previous line*
(If there is not space for one rtore line on screen, the cursor just aoves down one line*)
<Break> - Saw as <Return>*
<CTRD"0" - Shifts QE to Overwrite node.
<CTRL>"D n - Shifts QE to Delete node*
Shift <Insert> - Adds space after Djrsor position*
<CTRLXIrisert> - Inserts any one character t$>ed in after current cursor position* This allows
insertion of <CTRL> sequences that leave
<CTRL> ,, B" - Breaks the current line at the cursor position*
The other keys work normally* As long as there are spaces to the right, all other text will be Moved
to the right as text is inserted*
ESC - Returns to Cowhand node
IV*XZ QE Users Manual t p ♦<?
Overwrite Hode Connands
■
<CTRL> ir T n - Hoves cursor to first line of text screen*
<CTRL> ,, Z" - Hoves cursor to last line of text screen*
<CTRL>"H n - Hoves cursor to beginning of next word*
<CTRL>"E" - Hoves cursor to end of current line*
Tab - hoves cursor to next tab nark*
Shift Tab - Sets a tab nark in current cursor position.
<CTRL>Tab - Clears a tab nark fron present DJrsor position*
<CTRL>Up-Arrow - Hoves ojrsor up ore line*
<CTRL>Dowrr-Arrow - Hoves cursor down one line.
<CTRL>Left-Arrow - Hoves cursor left one character.
<CTRL>Right-Arrow - Hoves cursor right one character.
<Returri> - Hoves cursor down one line to first non-space letter.
<Break> - Saw es <Return>.
<CTRL>"I" - Shifts QE to Insert rode,
<CTRL>"D" - Shifts QE to Delete node.
Shift <Insert> - Adds space after cursor position.
<CTRLXLnsert> - Inserts any one character typed in after ojrrent cursor position. This allows
insertion of <CTRL> sequences that leave graphics characters.
<CTRL>"B U - Breaks the current lire at the current lire at the cursor position.
Any other keys behave nornally. Text is written over existing text.
ESC - Returns to Connand node.
IV* 17 QE t GlossarH » P ♦ 1
-
NOTICE ! The glossary which follows is intended for hackers and the idly curious* Users of (E will
only need the following half dozen words, all of which are invoked fro« FORTH:
QE and SE, described above, which get you into the GE Editor
n LOCK.ALL , which "locks" all the screens on drive n*, its cousin UM_0CK_ALL
n LQCKJBQOT , which "locks" the boot screens on drive n
WE , which is used like W£R£ to locate compilation errors*
— GEO W3CABILARY
This sets up a table to be used for the prowpt lire* This table is allotted 3*1 bytes* To
use, follow " with a four letter header starting with a quotes, then the prompt followed
by a quote* Thus**
" "com mtm)
" "SCU Re Hr He Lk Ulk Unlocked "
There fiust he 30 characters used between quotes*
"Kt" — addr QED
Variable signifying the keyboard address.
$?0F f —
The run-tine procedure compiled by ?0F* Works like $CF, except that it takes a flag fro«
the stack, rather than comparing two values on the stack* (See CASE glossary*)
ZEND — n QED
This constant holds the address of the end of the data for the current text screen*
XF — flag QED
Constant with value of 0, signifying False. Clarifies code*
ZT — flag QED
Constant with value of 1, signifying True* Clarifies code.
/COL — addr QED
Variable holding the number of the column the cursor is on*
/DONE — addr QED
Variable holding flag which is true if you are ready to leave QE, false otherwise*
/EXTRACT — n QED
This constant gives the memory address directly after XEI€>* Holds deleted characters for
use with SAVE*CH and EVAS*CH*
OTO — addr QED
Variable holding place in the stack of deleted characters* (Must be offset by /EXTRACT).
/IMAGE
— n . QED
This constant holds the location of the top of the GE display list.
/INSERT
IU*17 QE* GlossBr^» P*2
addr
QED
Variable holding flag which is true if EE is in Insert hode, false if not*
/KEY
— 3ddr QED
Holds the value of the key pressed ♦
Used in the CASE structure in the for m \
f ?0F xxx FO
?0F works like OF, except that it takes a flag fro* the stack, rather than comparing two
values on the stack ♦ (See CASE glossary ♦)
/LASTNUrfcER — addr QED
Variable holding the number of the screen last used before the present one.
/LINE
/NUrBER
/OLDDLA
/PROMPT
— addr QED
Variable holding the number of the line in memory to which the current row corresponds ♦
— addr QED
Variable holding the absolute value of the screen nutter «
— addr QED
This variable holds the address of the display list on the screen prior to EE's display
list* This is replaced on exiting QE*
nl — n2 QED
This is the prompt line, set up as a table, allotted 50 bytes* It appears at the bottom
of the screen ♦
/ROM
— addr QED
Variable holding the row the cursor is on*
aoor
/SMUDGE
Variable which is 1 if the screen number is positive and -1 if the screen number is
negative*
— addr QED
Variable signifying that there is a prompt* (0 if there is not)*
/STOP!
/TABS
— addr QED
Variable holding flag which says whether or not to stop the mode QE is in*
nl — n2 QED
Table of tabs, set originally to every eight characters. Changed by SETTAB arid CLRTAB*
MIRD-FLAG — addr QED
Variable which holds flag saying whether a digit typed in should be part of old digit, or
whether it should begin again. (e*g* 35 is displayed. Should a 1 typed in become 351 or
4).
/WERE — n BED
This constant points to nefwry address of the first text character to appear on the
ALENGTH — n (ED
Returns the length of the first row displayed on the editor's screen, not including
trailing blanks.
AIXOCATEJEMAGE — QED
Puts the address of the beginning of the text in the display so that the top of the video
screen holds the first line of the text*
BEEP! — QED
Flashes yellow to signify error, then returns to previous color* Sets /STOP! to true
(i.e. 1).
BEEP? — flag QED
Is /STOP! true (i.e. 1 )? If so, returns true flag.
BITJABLE r.l — rt2 FORTH
Table containing bit logic for lock/unlock flags. There are eight elements.
BREAKJJNE — QED
This is only operational if there is rocm below the line the cursor for an inserted line.
This shifts all of the line after the cursor down to the line below, leaving blanks after
the cursor on the original line, arid blanks before the cursor on the added line.
b — n QED
Constant that returns code field address of BEEP!
CASBUF — n FORTH
This constant narks the beginning of the cassette buffer (plus 2 bits )♦ This is used for
buffer since we don't use cassettes.
CH! ch — QED
Stores the character given at the locaton in rtetiory corresponding to the cursor location.
CH? — addr QED
Finds the location of the character in nettory which corresponds to the cursor location.
Puts that address on the stack.
Cm — ch QED
Fetches the character at the location in nefiory corresponding to the cursor location on
the screen.
C.PSE6 — QED
Turns off the keyboard, (i.e. won't read fron the keyboard after this).
CLRTAB — QED
Clears a tab nark fron current position. (Puts 0 in /TABS).
COTOATOJJOQP — QED
This runs continuously while in Cowiand Mode, picking up cofwands and executing then.
Aborts when /D0f£ returns false.
CURDQHN — QED
Moves cursor down 1 row.
IV. 17 QE» Glossary, p.-**
CURUP
— QED
Moves cursor up 1 row.
DI
— addr QED
This is the display list for GE* It has 22 lines of Hode 2, a divider of 1 Blank, and 1
line of Hode 2 for the prompt*
DELETE.ONE addr — QED
Replaces character at this address with a space*
DEL_AFTER — BED
Replaces all characters after cursor to end of text screen with spaces*
DELJSEFORE
Replaces everything ori
screen before the ojrsor with spaces*
DEL.CHAR — QED
Deletes a character arid uses SAME-CH to save the deleted character in a delete buffer*
DELJJNE — QED
Deletes the current line arid. Moves lines below up one*
DEL.SPACES — QED
Deletes all spaces ftm the Djrsor to the next non-space
ever cones first*
or
of the row*
DEL.HDRD — QED
Deletes all characters fro« the cursor to the next space* or the end of the row*
DEXJMT — QED
Sets up all of the DLI's , display list, colors, missiles, etc. Initializes everything
that needs it*
DISKIO — FORTH
Executes the system disk handler, Assunes that the device control block, has been set up
already <
DISPJftJH
This takes the norther of the screen in use and puts it on the prompt lire*
DOWN
— QED
If the cursor is at the botto* of the display, this Moves data up one line without
changing cursor (unless there is no hore data to scroll), otherwise this just roves cursor
down one line*
ED_COMMAND — QED
Executes cowrands entered in Cormand Hode*
ENDJ
Moves cursor to last non-blank character of current line.
EVAS CH — ch QED
Retrieves character at address of /EXTRACT + /EXTRACT? and subtracts ore fro* /EXTRACTP.
FLAGs — n FORTH
This constant leaves the location of the lock arid unlock flags*
GET.BYTE scrri — addr nask FORTH
Gets the appropriate address arid nask for the lock/unlock bit of this screen*
GET.KEY — ch QED
Gets the value of the key pressed arid puts its AT ASCII value on the stack* Also stores
this value in /KEY*
113
— n
This checks to see if the lire is indented. It returns the nunber of spaces indented.
*T_CHAR ch — QED
Inserts a character in row after cursor, if there is room*
INSERT J>*AR_R ch —
Takes a character arid tries to insert it to the right of the cursor* If it is at the end
of the row, it inserts a new line and inserts the character at the first column*
INSERT_D(MI — • QED
Inserts a line beneath Djrrent one if there is roo«* (i»e* blank lines at bottom of data
screen*) Used by INSERT-LUC.
INSERT JJNE — QED
Inserts a line beneath current one, if possible, and noves cursor to indentation of
■
previous line*
KBOTTOM — QED
Puts cursor at first colum of last line of text screen,
KDELETE — QED
Puts QE in Delete Mode, arid puts Delete prompt on prompt line*
KTXSERT — QED
Sets /INSERT to true and invokes TEXT.
KJOIN — QED
Joins together current line arid line below.
KOVERWRITE — QED
Sets /INSERT to false and invokes TEXT.
KQUTT — QED
Sets /DONE to true, alowing QE to quit,
KRECOVER — QED
Recovers a character fro* the deleted /EXTRACT buffer using EVAS-CH.
KRETURN — QED
Hoves down one line if possible and to the first non-blank character (using INDENT?),
KSCREEN — QED
Puts QE into Screen Mode, froti Comand Mode only, and sets /WEIRD-FLAG to false to allow
nunbers to be entered properly.
KSCROLLDOWN — QED
Used for scrolling the screen in Cofwand Node* Uses ROLLIF*
KSCROLLUP — QED
Used for scrolling the screen in Cownand Hode* Uses RQJJXHW*
KTOP — GED
Puts cursor at first line of text screen, in the first colum*
LEFT — tED
Hoves Djrsor one colunn to the left, unless it is at the first colunn* If it is, this
Moves the cursor to the last column of the row above, if there is a row above*
LENGTH — n QED
Returns the length of the first line of the text screen, not including trailing blanks*
LOCK scrr. — FORTH
"Locks" one screen by setting a bit in the cassette buffer (unused), thus preventing
writing that screen to the disk fro« QE*
LOCKED? scrn — FORTH
Returns "Locked" if the screen is locked, and "Unlocked" if it is unlocked*
LOCK.ALL drive — FORTH
Locks all screens on given drive, so that none can be written to in QE*
LDCKJ500T drive —
Locks all screens fron -11 to the end of the boot, (this Must be set into word) so that
the boot screens cannot be written to fron QE*
L0CKJJ3QK scrn — flag FORTH
Sets flags to 1 if the screen is locked* 0 if it is unlocked*
HAPJEtT scrn — nask offset FIFTH
Haps the screen nunber to the lock/unlock bit to which it corresponds*
HAP.CH! ch — QED
Changes ATASCIE character value to corresponding Internal value before storing it in
rtewory*
mjmm ch — ch qed
Identifies upper arid lower case letters, then naps letters to the comands they should
cause to occur*
WJ9CREEN scr — scr drv FORTH
Figures out which drive a screen is on} gives error if it is not a possible screen*
NEXT_SCREEN — QED
Writes current screen to disk using HRTH-SCREEN, reads in subsequent screen using
READ-SCREEN and adds 1 to MWER*
NGET — n QED
IV .17 QE» Glossary, p. 7
Returns the screen nunber being used*
open.k: — BED
This opens the Keyboard.
PROMPT addr — QED
T3k.es address of a prompt Message , finds its total length arid Moves it to address of
/PROMPT. Sets /SMUDGE to true.
QE — FORTH
Puts into QED vocabulary, uses DEXJXET to initialize everything, arid uses XED to enter
the editor, arid later to exit frcm the editor*
GED — FORTH
Establishes QED as the CONTEXT vocabulary*
READ JLAGS drv — FORTH
This word reads the lock, and unlock flags frcm the disk in given disk drive*
REAELSCREEN — GED
Reads screen held in /NLfrBER (sign held in /SIGN) fron disk* Puts Reading* ♦♦ prompt on
proript line*
RIGHT — QED
Moves cursor to the right one column, unless it is at the last column* If it is, this
Moves the cursor to the first column in the row beneath, if there is a row beneath*
ROLLDOW — QED
Scrolls screeri of text upward unless it is at bottom Does not hove cursor*
ROLLUP — BED
Scrolls screeri of text downward unless there is no «ore above current line* Does not hove
♦
SCREENJUOCKED? ~ QED
Checks to see whether the current screen is locked* If it is, puts "Locked" in inverse
video on prompt line, if not, puts "Unlocked" on pronpt line in inverse video*
SDIGIT — QED
Tak.es input and translates it to decimal numbers that /NUMBER can hold*
SE scrr. — FORTH
Given a screen nutiber, this simultaneously enters GE arid causes the screen to be read in*
SETDOWN.DL — QED
Reconstructs display list on screen prior to G£'s display list* Uses /OLDDLA*
SETTAB — QED
Sets tab Mark in current position. (Puts 1 in /TABS).
SETUP.DL — QED
Puts address of old display list in /OLDDLA*, sets up Dl as display list.
SET.COL col — QED
SETJJDC
IV. 17 QE, GlosssrH, p. 8
Given a column number, this puts it in /CCL arid moves player 0 (which forms the cursor)
over to that column*
n — (ED
Puts line from memory on screen} puts line number in /LINE*
SET.RDH row — QED
Sets up the cursor , using player 0, at the row, and puts value in /ROW*
SHEXDIGIT — QED
Takes hex numbers as input and translates then to numbers that /Nl&iEER can hold*
SINCREtfENT — QED
Increments /NlftBER by 1 or -1, depending ori the sign (held in /SIGN) *
SMINUS
— (ED
Subtracts 1 from ojrrent screen number*
SAVE.CH
— flag QED
Checks to see if /STOP! is true, or whether ESC has been hit* Returns true if either is
true*
ch QED
Saves a character in address found by adding /EXTRACT arid /EXTRACT?* Adds one to
/EXTRACT? ♦
STOTAL — (ED
Puts zero in /NUMBER and 1 in /SIGN*
TAB
TAB 1
— QED
Moves the cursor right to the next tab mark* as found in /TABS*
— QED
Puts a flag in /TABS at current position*
TABJBRD
Pops to beginning of next word* Will continue* line after line* till it finds a non-space
character*
TEXT
TEXTJS
— QED
This word is used to go into Insert or Overwrite Mode from Comand Mode* It oversees the
various commands that can be used in those modes* Gathers together marry little words for
use in actual editing*
— QED
Insert Mode* Deletes character to left of Djrsor, drawing back, rest of line to fill in*
Overwrite Mode** Overwrites character to the left of cursor with a space*
TEXT_CH ch — QED
If QE is in Insert Mode* this inserts the character to the right of the cursor using
B^ERT-CHAR-R*
If in Overwrite mode, this writes over the character under the cursor, moves cursor right
using RIGHT, and saves overwritten character with SAME-CH*
IV. 17 QE, Glossary, p. 9
TEXTJMBERT QED
Puts Irrsert prompt in prompt line, and sets /INSERT to 1 (true)*
TEXTJWER — QED
Puts Overwrite prompt on profit line, arid sets /INSERT to 0 (false)*
TEXT.RETURN QED
If QE is in Overwrite Hode, this noves cursor to first non-blank, character on lire below
current line. If CE is in Insert Hode, this inserts a lirie below current one, space
per witting, and Moves cursor to indentation of line above*
UNTAB — QED
Moves the oirsor to the next tab nark to the left, as found in /TABS.
UNTAB.WORD — QED
Hoves left till it finds a non-space character* Moves up screen till it finds a non-space
character or the beginning of the screen.
UNLOCK scrr. — FORTH
"Unlocks" a given screen by setting a bit in the cassette buffer, thus allowing one to
write that screen to the disk, in GE*
UNL0CKJ1L drive — FORTH
Unlocks all screens on given drive, so that all can be written to fro* GE*
UP — QED
If the Djrsor is at the top of the display, this *oves data down one lire without changing
cursor (unless there is no «ore data), otherwise it just *oves the cursor up ore row*
VECTOR nl — rtZ QED
This is the table (54 bytes long) containing the address of the actual keys for entering
cot-wands in CoHMand Hode*
WE scrn row col —
Recovers QE after disk errors* This will put GE up with scrn as the screen, and the
cursor at row arid col*
WEIRD.CHECK — QED
If /WEIRD_FLAG is false, this zeros the current screen nunber arid sets AORD.FLAG to
true*
WRITEJLAGS — FORTH
Writes the lock/unlock flags to the disk*
WRITE.SCREEN — QED
Writes screen held in /NUMBER (sign held in /SIGN) to disk* Puts "Writing* ♦♦" prompt
on prompt line*
XED — QED
Puts in original QE proupt giving Revision nurtber, etc. Sets up everting, initializes
everything, puds into COMMAND JJDOP,
HOTaT to write good forth
FORTH suffers from a combination of bad press arid bad programmers* It is actually easier to
write good FORTH than good anything else, since it is flexible, imposes few restrictions, and
extracts no penalty for short programs, (Short programs, incidentally, are where it's at - breaking
things up into small, sensible, lucid pieces is a key to good programming)*
«
Hha write good FORTH?
Good code is faster to write, if you consider total time, since it comes from clear thinking and
good organization, arid it is much easier to debug. You can understand and modify good code in
amazingly shorter time*
Finally, you're much more employable if you write good code* Should a prospective employee tell
me that he or she prides him or herself in writing good, clear, maintainable, well-documented FORTH I
would, after picking myself up off the floor, endeavor to hire the person or. the spot.
How to write good FORTH:
You need to (1) know what good FORTH is, (2) discipline yourself to write it* Item (1) will be
addresed next* For (2), I've observed that a few thoughtful rewritings of a reasonably sized piece
of code will not only help a decent programmer understand what good code is, but will also establish
the necessary habits so that writing passable code becomes almost automatic, and good code a distinct
possibility*
What is good FORTH?
Good FORTH consists of short, well thought out pieces* A word should rarely take up more than
half a screen* If you use more than that, see whether you can break, up the word into smaller, more
coherent pieces* A good FORTH word is one which is easy to understand, and which you might be
tempted to use again elsewhere*
Good FORTH is vertical, not horizontal* That is, there are few words per line and the lines are
left-indented in an intelligent fashion. DOs and LOOPs, BEGINs and UMTLs, IFs, T*£Ns, and ELSEs,
etc* are all left justified, with inner groupings to the right of outer ones. Take a look, at the
Swarthmore source code to see what this means.
Each line should contain no more than a single idea.
A comment accompanying each word should show its effect on the stack, preferably with helpful
mnemonic symbols for the stack, elements*
Words should be liberally sprinkled with comments. Hore lengthy comments can be put after the
>" or "}S". The best code is almost self -documented.
The first line of a screen should consist of a comment which describes the contents of the
screen. You should rarely start with more than half a screen full of code*
Will you go broke buying the number of disks necessary to write good FORTH? Hardly* Even in
KJ* How t,o write good FORTH , P ♦ 2:
this expansive forn, FORTH gets you a lot of Mileage ♦ Horeover, few itens connected with computers
are as cheap as disk space* Finally, truth to tell, revisions and reworking usually result in
screens filling up More than the nir.iMal reconnended (starting Minimally gives you rooM for such
expansion) i
FORTH is supposedly a "stack oriented" language, but the prograMMer should not be stack
oriented. Juggling several elements or. the stack can cause a surprising nuriber of errors* In almost
all situations, it's Much clearer and leads to Many fewer errors if you introduce sensibly naned
variables* It is hard to find a situation when such a practice will Measurably slew down a prograM*
It is possible to juggle stack elements by sending the* to and fro« the return stack (it's possible
to do lots of wild things in FORTH), but it's usually just not worth it*
If you siMply Must play with several iteMs or. the stack, you're probably best off Making up
special stack. Manipulation words* If a word deals with several iteMs on a stack, I've also found it
very helpful to put in full connent lines within the word which show the stack, changes in clear
Mnehonics*
Hell-thought-out nanes can cor.tr ibute intensely to good code* It's worth spending tine waking up
useful nanes (self-docunenting code, again)* One helpful approach is to try to nane what the word
does, not how it does it* .Don't use an unidentified nunber in a word. Either identify it in a
content or define a constant (with a good nane) arid use it in the axle.
Avoid abbreviations when you're writing code. The extra typing is trivial and the clarity
introduced is considerable. It's fair and reasonable to introduce abbreviations in a
testing/debugging session, however.
•
Is our code good?
It varies. It's getting better. At first we conttitted the negation of the above ideas. Look
over our source code and see what you like and what is clear. There are probably 8 different
prograMMers represented on the SwarthMore disks, so there are lots of different styles, ideas, arid
Further thoughts or. writing good FORTH are to be found in Leo Brodie's Starting FORTH*
9> o\> OsN^VS
%o * Hal
CXvv^ H. ^ c^rr^O^v^Vv^ \xnf^oAr-^ ^vtMSW)
^tKy / ,
o
«<A Lt/^ A^v-*^ < S7C5^wltK^ . I/O
As! MM . EXT EL. V K.S
i i
(778780 - SRC) '
n X EDIT
EDITOR
SCR
L
N
LL
UL
DOIT
e
- Enter editor vocabulary on scr^|n n
RECEIVED
NOV 1 o 1982
SPECIAL PROJECTS
- VOCABULARY name - used to get to the Editor words.
- VARIABLE containing the current edit screen ^T*"^
- List current screen.
- List next screen.
SRC DEST COPY
FIRST LAST SHOW
n LIST
Line Edit Functions
n TL
n HL
n DL
n IL
n RL
n SL
- List lower 8 lines for screen editor.
- List upper 8 lines for screen editor.
- Take the top 16 lines on the TV display and put into
the upper or lower half of the edit SCR. (whichever
was last displayed). Use the colleen cursor and edit
keys to change the screen. Move the cursor to the
DOIT line and hit RETURN.
DO NOT HIT RETURN while editing the LL or UL screens.
- copy block SRC to block #DEST.
- list all blocks inclusive.
- set SCR to n and list the block.
n BL
n SCR CL
n $
n %
FLUSH
- Type line n and save it in PAD.
- Hold line n in PAD.
- Delete line n - save it in PAD.
- Insert PAD after line n.
- Replace line n with PAD.
- Spread to create blank line n by pushing every thing
down and losing line F.
- Blank line n - not saved in PAD.
- Move line n of Screen #SCR to PAD.
- Put text following $ up to RETURN onto line n.
- Insert text following % up to RETURN after line n.
- RETURNS to FORTH Vocabulary. Writes out changed
blocks.
Currently 7/8/80 8 Load loads the assembler, Ed Logg's Colleen I/O and
Graphics words and this Editor.
1+!
1-
OSET
2*
2/
CHH
HH
CH?
H?
TBL
ALLOC
ARRAY
S?
RP
R?
BDUMP
(addr->)
(n-? n-1)
(addr-»
(n n)
(n ~f n)
(b ^ )
(u ^ )
(addr )
(addr )
( ~7> n)
(n -» )
(n )
( -> )
( -?n)
( -y )
(addr ,addr -~> )
ATARI FIG ADDITIONS
(From DECUS)
^ -
add one to word at addr
subtract one from TOS
set word at address to 0
mult. TOS by 2
div. TOS by 2
faster than
type value of LSB of TOS as 2-digit HEX-
type value of TOS in unsigned HEX
type value of byte at addr in HEX
type value of word at addr in unsigned
HEX
return Index for next outer most DO-LOOP
;defines ROM table (like DECUS, CALTECH
IARRAY)
allocate n words in RAM
CREATE named ARRAY, n words long, returns
addr of first element when exe
TYPE contents of param stack, without removing them
point to TOP of RETURN (control) stack
TYPE contents of return stack (non-destructive)
Display contents of addr to addr (inclusive)
always in increments of 8 bytes.
TERMINAL INPUT-OUTPUT
.R
D.
D.R
CR
SPACE
SPACES
DUMP
TYPE
COUNT
7TERMINAL
KEY
EMIT
WORD
n - )
n fieldwidth — )
d - )
d fieldwidth - )
- )
- )
n - )
- )
addr u — )
addr u — )
addr - addr+1 u )
- f )
- c )
c - )
addr n - )
c - )
Print number.
Print number, right-justified in field.
Print double-precision number.
Print double-precision number, right-justified in field.
Do a carriage return.
Type one space
Type n spaces.
Print message (terminated by ").
Dump u words starting at address.
Type string of u characters starting at address.
Change length-byte string to TYPE form.
True if terminal break request present.
Read key, put ascii value on stack.
Type ascii value from stack.
Read n characters (or until carriage return) from input to address.
Read one word from input stream, using given character (usually blank) as delimiter.
INPUT-OUTPUT FORMATTING
NUMBER ( addr - d )
<# ( - )
# ( d - d )
#S ( d - 0 0 )
SIGN ( n d - d )
#> ( d - addr u )
HOLD ( c - )
Convert string at address to double-precision number.
Start output string.
Convert next digit of double-precision number and add character to output string.
Convert all significant digits of double-precision number to output string.
Insert sign of n into output string.
Terminate output string (ready for TYPE).
Insert ascii character into output string.
DISK HANDLING
LIST
LOAD
BLOCK
B/BUF
BLK
SCR
UPDATE
FLUSH
EMPTY-BUFFERS
screen — )
screen — )
block - addr )
- n )
- addr )
- addr )
- )
- )
- )
List a disk screen.
Load disk screen (compile or execute).
Read disk block to memory address.
System constant giving disk block size in bytes.
System variable containing current block number.
System variable containing current screen number.
Mark last buffer accessed as updated.
Write all updated buffers to disk.
Erase all buffers.
DEFINING WORDS
: xxx
VARIABLE xxx
CONSTANT xxx
CODE xxx
( - )
( - )
( n - )
xxx: (
(n - )
xxx: (
( - )
( - )
addr )
n )
<BUILDS . . . DOES> does: ( - addr )
Begin colon definition of xxx.
End colon definition.
Create a variable named xxx with initial value n; returns address when executed.
Create a constant named xxx with value n; returns value when executed.
Begin definition of assembly-language primitive operation named xxx.
Used to create a new defining word, with execution-time "code routine" for this data
type in assembly.
Used to create a new defining word, with execution-time routine for this data type in
higher-level Forth.
VOCABULARIES
CONTEXT
CURRENT
FORTH
EDITOR
ASSEMBLER
DEFINITIONS
VOCABULARY xxx
VLIST
addr )
ci d r* J
- )
- )
- )
- )
- )
- )
Returns address of pointer to context vocabulary (searched first).
Returns address of pointer to current vocabulary (where new definitions
Main Forth vocabulary (execution of FORTH sets CONTEXT vocabulary).
Editor vocabulary; sets CONTEXT.
Assembler vocabulary; sets CONTEXT.
Sets CURRENT vocabulary to CONTEXT.
Create new vocabulary named xxx.
Print names of all words in CONTEXT vocabulary.
MISCELLANEOUS AND SYSTEM
( ( - ) Begin comment, terminated by right paren on same line; space after (.
FORGET xxx ( - j Forget all definitions back to and including xxx.
ABORT ( - ) Error termination of operation.
'xxx ( - addr ) Find the address of xxx in the dictionary; if used in definition, compile address.
HERE ( - addr ) Returns address of next unused byte in the dictionary.
PAD ( — addr ) Returns address of scratch area (usually 68 bytes beyond HERE).
IN ( - addr ) System variable containing offset into input buffer; used, e.g., by WORD.
SP@ ( — addr ) Returns address of top stack item.
ALLOT ( n — ) Leave a gap of n bytes in the dictionary.
( n — ) Compile a number into the dictionary.
Forth Interest Group, P.O. Box 1105, San Carlos, CA 94070
FORTH HANDY REFERENCE
Stack inputs and outputs are shown; top of stack on right.
This card follows usage of the Forth Interest Group
(S.F. Bay Area); usage aligned with the Forth 78
International Standard.
For more info: Forth Interest Group
P.O. Box 1105
San Carlos, CA 94070.
Operand key: n, n1, .
d, dl. .
u
addr
b
c
f
16-bit signed numbers
32-bit signed numbers
16-bit unsigned number
address
8-bit byte
7-bit ascii character value
boolean flag
STACK MANIPULATION
DUP
DROP
SWAP
OVER
ROT
-DUP
>R
R>
R
(
)
(
n — n n
n - )
( n1 n2 - n2 n1 )
( n1 n2 - n1 n2 n1
( n1 n2 n3 - n2 n3
( n - n ? )
(n - )
( - n )
( - n )
Duplicate top of stack.
Throw away top of stack.
Reverse top two stack items.
) Make copy of second item on top.
n1 ) Rotate third item to top.
Duplicate only if non-zero.
Move top item to "return stack" for temporary storage (use caution).
Retrieve item from return stack.
Copy top of return stack onto stack.
-
-
NUMBER BASES
DECIMAL (
HEX
BASE
- )
( - )
( - addr )
Set decimal base.
Set hexadecimal base.
System variable containing number base.
ARITHMETIC AND LOGICAL
+
D+
/
MOD
/MOD
•/MOD
V
MAX
MIN
ABS
DABS
MINUS
DMINUS
AND
OR
XOR
( n1 n2 - sum )
( d1 d2 - sum )
( n1 n2 - diff )
( n1 n2 - prod )
( n1 n2 - quot j
( n1 n2 -* rem )
( n1 n2 — rem quot )
( n1 n2 n3 - rem quot )
( n1 n2 n3 - quot )
( n1 n2 — max )
( n1 n2 — min )
( n — absolute )
( d — absolute )
( n - -n )
( d - -d )
( n1 n2 - and )
( n1 n2 - or )
( n1 n2 - xor )
COMPARISON
<
( n1 n2 - f )
>
( ni n2 - f )
( nl n2 - f )
0<
( n - f )
0=
( n - f )
MEMORY
@
( addr - n )
!
( n addr - )
C@
( addr - b )
C!
( b addr - )
?
( addr — )
+!
( n addr - )
CMOVE
( from to u —
FILL
( addr u b - )
ERASE
( addr u -* )
BLANKS
( addr u - )
CONTROL STRUCTURES
DO . . . LOOP do: ( end+1 start
I ( - index )
LEAVE ( - )
DO . . . +LOOP do: ( end+1 start
-Hoop: ( n - )
IF . . . (true) . . . ENDIF if: ( f - )
IF . . . (true) . . . ELSE if: ( f - )
. . .(false). . .ENDIF
BEGIN . . . UNTIL . until: ( f - )
BEGIN . . . WHILE while: ( f - )
. . . REPEAT
- )
- )
Add double-precision numbers.
Subtract (n1-n2).
Multiply.
Divide (n1/n2).
Modulo {i.e. remainder from division).
Divide, giving remainder and quotient.
Multiply, then divide (n1*n2/n3), with double-precision intermediate.
Like */MOD, but give quotient only.
Maximum.
Minimum.
Absolute value.
Absolute value of double-precision number.
Change sign.
Change sign of double-precision number.
Logical AND (bitwise).
Logical OR (bitwise).
Logical exclusive OR (bitwise).
True if n1 less than n2.
True if n1 greater than n2.
True if top two numbers are equal.
True if top number negative.
True if top number zero (i.e., reverses truth value).
Replace word address by contents.
Store second word at address on top.
Fetch one byte only.
Store one byte only.
Print contents of address.
Add second number on stack to contents of address on top.
Move u bytes in memory.
Fill u bytes in memory with b, beginning at address.
Fill u bytes in memory with zeroes, beginning at address.
Fill u bytes in memory with blanks, beginning at address.
Set up loop, given index range.
Place current index value on stack.
Terminate loop at next LOOP or +LOOP.
Like DO . . . LOOP, but adds stack value (Instead of always '1') to index.
If top of stack true (non-zero), execute. (Note: Forth 78 uses IF . . . THEN.]
Same, but if false, execute ELSE clause. (Note: Forth 78 uses IF . . . ELSE . . . THEN.)
Loop back to BEGIN until true at UNTIL (Note: Forth 78 uses BEGIN . . . END ]
Loop while true at WHILE; REPEAT loops unconditionally to BEGIN.
(Note: Forth 78 uses BEGIN . . . IF . . . AGAIN ]
! .
the documentation
"Going Forth" is:
on Fig-Forth 1.4 (Calfee)
Here is
The address for
Creative Solutions
14625 Tyneuiick Terrace
Silver Springs MD.
This stuff doesn't seem to cover the editor, so I'm sendin 9
a Xerox of the paper stuff. The editor is pretty simple, just
whatever you do don't hit RETURN. Ed R°tberg £as
(less lethal) version. You might try him at 745-1090 (Videa)
20906
r
c
■ -
a;
C
46
><? rr
M y br<? /)
00
# la*
T~~
in Htfrt
defy '\f
r
7^
!
I
3
r
7
8
9
0
12!
?
1^'
c.
c
D
CO
c
o
o
5
29
: :
1
35
39
44
GRAPHICS and CONTROLLER words
PADDLE 1-1
PTRIO 1-1
STICK
1-1
STRIO
1-1
GRAPHICS 1-0
GR.
<n>
COLOR
C.
<x> <y> PLOT
PL
1-0
2-0
<*> <y> DRAWTO 2-0
DR.
<x> <y> POSITION 2-0
P03.
PUT
1-0
GET
0-1
<x> <y> LOCATE
2-1
<n> Cc> <1> SE. 3-0
SETCOLOR
Cft? <.p> <d> <v>
SOUND
SO.
4-0
. c
PLAYER/MISSILE Graphics
n=0~7 Reads paddle <n>. Value is O-FF
n-0~7 Reads paddle trigger button <n>
O-pressedi 1 =no t pressed.
n=0-3 Reads joystick <n>. Lower 4 bits
represent 4 directions. (0=0N l-OFF)
D3-right, D2-left, Dl~down, DO-up
n=0-3 Reads joystick <n> trigger button
Oppressed/ l=not pressed
Open screen in graphics mode <n> (BASIC
mode #, NOT ANTIC). Add 16 (dec. ) to
eliminate split screen. Add 32 (dec. )
to prevent clearing screen
Set "color" (pixel data) for subsequent
PLOT or DRAWTO.
Plot a point at (<x>, <
(0*0) is upper left corner,
reference manual for limits
modes.
screen.
See BASIC
in particular
Draw a line from current position to
(<x>, <y>).
Set current position to ( <x>, <y> ) . Does
not plot, used with PUT, GET.
Put the value <n> at current position.
Current <x> is then incremented.
Get the value of pixel data at current
position. Current <x> is then incremented
Same as <x> <y> POS. GET
Set color register <n> to color <c>>
luminance <1>.
Set sound channel <n> to pitch <p>,
"distortion" <d># and volume <y>
Consult BASIC reference manual for
further info. In general, storing to
F1AUD, C1AUD, etc. will be easier.
<n>
PLAYER 1-0
PBASE constant
Set up player-missile graphics with <n>
(n=l or 2) vertical line resolution.
Returns base address of player/missile
DMA area. This is set by GR. , and changes
with different modes.
<x> <n> HPOS!
2-0
n=0-7 Set PLAYER/MISSILE <n> horizontal
position to <x>. MISSILE 0 = PLAYER 4 etc
n
<x> <n> SIZE!
c
0
a-
■
u
o
o
n=0-4 Set size of PLAYER <n> < all
if n=4 > to <x>. x = l ~> double size.
x=3 => quad size.
MISSILES
<*> <n> COLPM! 2-0
n~0-3, x =0-2 54 step 2
Set color of PLAYER /MISSILE <n> to <x>. Note
that MISSILE <n> is same color as PLAYER <n>
unless "fifth player enable" is selected.
( see PRIOR in hardware manual )
PRIOR byte
var iab le
VDELAY byte
var iab 1 e
You should store the desired priority value
here. Consult the hardware manual for detail
You should store the "vertical delay" bits
here. This is only needed if single line
CIO words
n
IOCS
1-0
CIO
0-0
ICDNO
ICCOM
ICSTA
ICBAL
ICBLL
I1CAX
I2CAX
ICPTL
<n>
AC 10
1-0
CIOA
0-1
<2> <1> <d> OPEN 3-0
CLOSE
0-0
positioning is needed with double line graphics
resolution. Consult the hardware manual.
n=Q-7 Set "current" IOCS to <n>. IOCB 0 is
normally open to E: and should not be
changed. IOCB 1 is used by GRAPHICS commands
and should be restored before using them,
(ed. note.- I know that this should have been
IOCB 6t and that words shouldn't make such
assumptions. I didn't write this stuff, I'm
just documenting what exists. )
Calls CIO. Assumes that " <n> IOCB " has been
done, and that I0C3 n is correctly set up.
You should carefully read the 0. S. manual.
The following "constants" will refer to the
"current" IOCB:
Device # in HATABS. (byte)
Command (byte)
Status (byte)
Buffer Address (word )
Buffer Length (word)
AUX1 (byte)
AUX2 (byte) (note: these are odd to allow
use with fixed-length-name FORTHs)
"put-byte" address (word) (used by BASIC/
shun like plague)
Call CIO with acc
ICBLL-0
n. Normally used with
Call CIO and put returned acc
Normally used with ICBLL=0
on stack.
Open current IOCB with AUX1=<1>, AUX2=<2>
<d> pointing to d vc : f i 1 e. e x t. <d> should
be just a pointer (no count) and string
should be terminated with non-alphanumeric.
Close the current IOCB. One of the quickest
ways to hang FORTH is to type CLOSE without
previously typing <n> IOCB. This closes
IOCB Oi then returns to the outer interpreter
which attempts to read from IOCB 0. The
resulting error message also tries to get out
via IOCB 0.
PUT
1 — o
Do a "out character" with char=<n>
r
SI
C
E
c
01
c
0
o
6
GET
0-1
Get one character from current IQCB, returning
character on stack.
c
Fig
1.
4 Disk Block Numbering
+ + + + +
1 0 ! TYP { DRV ! BLOCK !
+ + + + +
i o « r> « 11 «
: l
+ —
bits
Where:
TYP =
0
1
2
3
(add
< "
0000
2000
4000
6000
)
)
)
)
> 810 type 5 1/4" single dens.
> 815 or 8" double dens.
> 8" single dens. DEC interleave
8" 11 " non-interleaved
•>
DRV •
0
(add
0000
)
-->
Dr i ve
1
1
( "
0800
)
->
it
2
< "
1000
)
->
it
3
3
( "
1800
)
->
it
4
Dictionary Entries
Fig t. 3 and earl ier
r
cnt
- +
name
NFA
I
+•
I
+
!
+-
LFA
(link)
CFA
I
-+
>code
+
! PFA
I
!
params :
i
+■
i
Fig 1.4
LFA
— +
i
J (link)
+
! count
i
i
•+•
!
+ - -
• name
NFA
:
+
i
i
■+•
CFA
->code
i
*
PFA
params
+
i
i
r
Live Music
Archive
Librivox
Free Audio
Metropolitan Museum
Cleveland
Museum of Art
Internet
Arcade
Console Living Room
Open Library
American
Libraries
TV News
Understanding
9/11